Providing Component Documentation

Component documentation helps developers use your components effectively. You can provide interactive examples, documentation, and specification descriptions for a component, event, or interface.

A component, event, or interface is also known as a root definition.

Viewing the Documentation

When a root definition is marked access="global", it’s surfaced in the Component Library in your org. For managed packages and namespaces you own, components with either access="global" or access="public"(default) are surfaced in the Component Library. Each root definition page can display up to three tabs in the following order.

Example: Displays interactive examples denoted by the <aura:example> tag in the .auradoc file. This tab is hidden if no examples are wired up in your .auradoc file. See the Providing an Example Component section below.
Documentation: Displays the content of the .auradoc file. This tab is hidden if an .auradoc file is not available for your root definition. See the Writing the Documentation section below.
Specification: Displays the description of the root definition, attributes, and methods. For managed packages and namespaces you own, attributes and methods with either access="global" or access="public"(default) are surfaced. See the Providing Inline Descriptions section below.

Writing the Documentation

The main documentation for a root definition is surfaced via the Documentation tab on a root definition page, for example, https://developer.salesforce.com/docs/component-library/bundle/lightning:avatar/documentation.

Provide your content in HTML markup and describe what a component is and what it does. Add code samples to help developers use your component, event, or interface easily.

To provide documentation, click DOCUMENTATION in the component sidebar of the Developer Console, which creates a .auradoc file. The following example shows the content of avatar.auradoc.

A .auradoc file contains these tags.

Tag	Description
`<aura:documentation>`	Required. The top-level definition of the DocDef
`<aura:description>`	Required. Describes the component using 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 `<aura:component>`.
`<aura:example>`	Optional. References an example that demonstrates how the component is used. Supports 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

The example component is rendered as an interactive demo in the Example tab of a root definition page when it’s wired up using aura:example.

1<aura:example name="exampleAvatarBasic" ref="lightningcomponentdemo:exampleAvatarBasic" label="Basic Avatar">
2    <p>The following example creates an avatar with the default size and variant. The initials "BW" is displayed if the image path denoted by the <code>src</code> attribute is invalid or fails to load for any reason, such as when the user is offline.</p>
3  </aura:example>

The following is an example component that demonstrates how lightning:avatar can be used.

Supported HTML Tags in .auradoc Files

We recommend using the following tags in your documentation.

<a>—Link
<p>—Paragraph
<ul>—Bulleted List
<ol>—Numbered List
<li>—List item in a bulleted or numbered list
<code>—Code formatting
<pre>—Code block
<h4>—Section heading
<table>—Table with rows and columns of data

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:method>`	`1<aura:method name="setCustomValidity" description="Sets a custom error message."> 2 <aura:attribute name="message" type="String" 3 description="The string that describes the error. If message is an empty string, the error message is reset."/> 4</aura:method>`
`<aura:registerEvent>`	`<aura:registerEvent name="keydown" type="ui:keydown" description="Indicates that a key is pressed"/>`

Lightning Aura Components Developer Guide