LWC Documentation

Documentation

Documentation Flow

Use this page in order:

1. Start with required elements to understand the baseline expectations.
2. Use the JSDoc section as your implementation reference.
3. Use inline comments guidelines to keep code readable without over-commenting.

Required Documentation Elements

For Classes:

• @description - Brief description followed by expanded details
• Key features - Bulleted list of main features/capabilities
• Additional context - Explanation of how the component works and interacts with other components
• @example - Usage example in code block
• @author - Comma-separated list of contributors
• @since - Date and initial implementation information
• @see - References to related components/utilities

For Methods:

• Description - Plain text description of what the method does
• @param - Parameter descriptions with types
• @returns - Return value description with type
• @example - Usage example when helpful

JSDoc Requirements

Usage: All public methods and complex private methods must have JSDoc comments.

Class Documentation:

/**
 * @description Reusable action button component with multiple variants and customization options.
 *
 * This component provides a flexible button implementation that supports various
 * styles, icons, and actions. It can be used as a standard button or as a link,
 * and supports navigation, message channel publishing, and custom click handlers.
 *
 * Key features:
 * - Multiple button variants (brand, neutral, destructive, etc.)
 * - Icon support (left, right, or both)
 * - Navigation support via NavigationMixin
 * - Message channel publishing
 * - Custom styling via CSS custom properties
 * - Full accessibility support
 *
 * @example
 * <c-example-child
 *     label="Click Me"
 *     variant="brand"
 *     icon-name="utility:add"
 *     onactionclicked={handleClick}>
 * </c-example-child>
 *
 * @author contributor1
 * @since 01-01-2024 Initial Implementation - contributor1
 *
 * @see NavigationMixin For navigation functionality
 * @see MessageContext For message channel support
 */
export default class ExampleChild extends NavigationMixin(LightningElement) {
}

Method Documentation:

/**
 * Sets focus on the button element.
 * @returns {void}
 */
@api focus() {
    const button = this.template.querySelector('button');
    if (button) {
        button.focus();
    }
}

/**
 * Handles the click event and dispatches custom event.
 * @param {Event} event - The click event object
 * @returns {void}
 */
handleClick(event) {
    this.dispatchEvent(new CustomEvent('actionclicked', {
        detail: {
            recordId: this.recordId,
            action: 'clicked'
        },
        bubbles: true,
        composed: true
    }));
}

/**
 * Validates the component state and returns validation result.
 * @returns {Object} Validation result with isValid flag and error message
 * @returns {boolean} returns.isValid - Whether the component is valid
 * @returns {string} returns.error - Error message if invalid
 */
@api validate() {
    if (!this.value) {
        return {
            isValid: false,
            error: 'Value is required'
        };
    }
    return {
        isValid: true,
        error: undefined
    };
}

Inline Comments Guidelines

• Prefer self-documenting code - Use clear variable and method names
• Add comments when logic is complex - Explain "why" not "what"
• Avoid obvious comments - Don't restate what the code clearly shows
• Update comments with code changes - Keep comments in sync with code

Good Example:

// Use safe navigation to avoid errors when record type is null
const objectName = record?.getSObjectType()?.getDescribe()?.getName();

Bad Example:

// Set the label
this.label = 'Click Me';

Related Standards

• Component API
• Conventions and Structure
• Templates and Slots
• Accessibility

Change History

Version 1.0 - 2026-03-26

• Added initial version history tracking for this document.

Last Updated: 2026-03-26 Version: 1.0