Providing Component Documentation

Component documentation helps others understand and use your components.
You can provide two types of component reference documentation:
  • Documentation definition (DocDef): Full documentation on a component, including a description, sample code, and a reference to an example. DocDef supports extensive HTML markup and is useful for describing what a component is and what it does.
  • Inline descriptions: Text-only descriptions, typically one or two sentences, set via the description attribute in a tag.

To provide a DocDef, click DOCUMENTATION in the component sidebar of the Developer Console. The following example shows the DocDef for np:myComponent.

Note

Note

DocDef is currently supported for components and applications. Events and interfaces support inline descriptions only.

<aura:documentation>
    <aura:description>
        <p>An <code>np:myComponent</code> component represents an element that executes an action defined by a controller.</p>
        <!--More markup here, such as <pre> for code samples-->
    </aura:description>
    <aura:example name="myComponentExample" ref="np:myComponentExample" label="Using the np:myComponent Component">
	<p>This example shows a simple setup of <code>myComponent</code>.</p>
    </aura:example>
    <aura:example name="mySecondExample" ref="np:mySecondExample" label="Customizing the np:myComponent Component">
       <p>This example shows how you can customize <code>myComponent</code>.</p>
    </aura:example>
</aura:documentation>

A documentation definition contains these tags.

Tag Description
<aura:documentation> The top-level definition of the DocDef
<aura:description> Describes the component using extensive HTML markup. To include code samples in the description, use the <pre> tag, which renders as a code block. Code entered in the <pre> tag must be escaped. For example, escape <aura:component> by entering &lt;aura:component&gt;.
<aura:example> References an example that demonstrates how the component is used. Supports extensive HTML markup, which displays as text preceding the visual output and example component source. The example is displayed as interactive output. Multiple examples are supported and should be wrapped in individual <aura:example> tags.
  • name: The API name of the example
  • ref: The reference to the example component in the format <namespace:exampleComponent>
  • label: The label of the title

Providing an Example Component

Recall that the DocDef includes a reference to an example component. The example component is rendered as an interactive demo in the component reference documentation when it’s wired up using aura:example.

 <aura:example name="myComponentExample" ref="np:myComponentExample" label="Using the np:myComponent Component">

The following is an example component that demonstrates how np:myComponent can be used.

<!--The np:myComponentExample example component--> 
<aura:component>
    <np:myComponent>
        <aura:set attribute=”myAttribute”>This sets the attribute on the np:myComponent component.</aura:set>
        <!--More markup that demonstrates the usage of np:myComponent-->
    </np:myComponent>
</aura:component>
    

Providing Inline Descriptions

Inline descriptions provide a brief overview of what an element is about. HTML markup is not supported in inline descriptions. These tags support inline descriptions via the description attribute.

Tag Example
<aura:component> <aura:component description="Represents a button element">
<aura:attribute> <aura:attribute name="label" type="String" description="The text to be displayed inside the button."/>
<aura:event> <aura:event type="COMPONENT" description="Indicates that a keyboard key has been pressed and released"/>
<aura:interface> <aura:interface description="A common interface for date components"/>
<aura:registerEvent> <aura:registerEvent name="keydown" type="ui:keydown" description="Indicates that a key is pressed"/>

Viewing the Documentation

The documentation you create will be available at https://<myDomain>.lightning.force.com/auradocs/reference.app, where <myDomain> is the name of your custom Salesforce domain.