Skip to content

Latest commit

 

History

History
47 lines (45 loc) · 2.6 KB

documentation.md

File metadata and controls

47 lines (45 loc) · 2.6 KB

Garden documentation

The JSDoc applied to exported element components is extracted during the website build process and used to generate API prop tables seen on component pages. Therefore, Garden adheres to a strict set of rules for element component documentation. Other additional component documentation is generally left to developer discretion, but should honor Garden content guidelines. The following list enumerates the standard rules for Garden element component documentation:

  • All element-level components must be embellished with the @extends JSDoc tag. These tags will indicate the HTMLElement interface of the element rendered by the component.
  • All element component props must be documented
  • Props will be consistently documented using present simple, third person (understood) singular grammar. Prefer active vs. passive voice.
    • A good mechanism for formulation is to think “it _____” where “it” refers to the prop being described and the filled-in blank becomes the prop’s description
    • Limited exceptions to this rule may be considered on a case-by-case basis where the grammar construct feels clunky
    • Do & don't examples:
      • ✅ “Specifies the font size”
      • 🚫 “Specify the font size”
      • ✅ “Determines light mode styling”
      • 🚫 “Whether light mode styling is used”
      • ✅ “Applies danger styling” (active)
      • 🚫 “Determines if danger styling is used” (passive)
    • Function-type props must document all @param values and any relevant @returns value
    • Use lowercase for component names referenced within prop descriptions
    • Consider opportunities for adding internal cross-reference or external URL links
      • See the Multiselect API renderItem prop for an example of an internal cross-reference
      • See the Dropdown API for an external linking example
    • Only add prop JSDoc to TypeScript prop interfaces
      • Refrain from documenting React defaultProps
      • Refrain from documenting styled components props
    • Use @ignore to prevent a prop from being added to generated documentation. Use this tag sparingly to hide internal-only APIs.