Documentation Guidelines

Guidelines for documenting Ignite UI Angular

Each publicly exported member should be documented

Start with succinct description of the document member

Focus on what it does, instead of how it does it. Try to stick to maximum of 1-2 sentences. Extra information and explanation can be added in @remarks later down.

DO

/**
 * Provides a way to display an image, icon or initials.
 *
 * ...
 */
@Component({
    selector: 'igx-avatar',
    templateUrl: 'avatar.component.html'
})
export class IgxAvatarComponent {}

AVOID

/**
 * **Ignite UI for Angular Avatar** -
 * [Documentation](https://www.infragistics.com/products/ignite-ui-angular/angular/components/avatar.html)
 *
 * The Ignite UI Avatar provides an easy way to add an avatar icon to your application.  This icon can be an
 * image, someone's initials or a material icon from the google material icon set.
 *
 * ...
 */
@Component({
    selector: 'igx-avatar',
    templateUrl: 'avatar.component.html'
})
export class IgxAvatarComponent {}

---

Public, private and protected modifiers

While in TypeScript, each member is public by default, make sure to explicitly mark each member with its respective modifier.

DO

class Klass {
    public someMethod() {
        ...
    }
}

AVOID

class Klass {
    someMethod() {
        ...
    }
}

---

Skip public members not relevant to the public API

Class members which are marked public only because they are used in a template but are not public API should be documented and marked with the @hidden and @internal tags.

DO

class Klass {
    /**
     * Apply CSS styles based on some internal state.
     *
     * @hidden
     * @internal
     *
     */
    public get styles() {
        ...
    }
}

AVOID

class Klass {
    /**
     * Apply CSS styles based on some internal state.
     *
     */
    public get styles() {
        ...
    }
}

---

Keep the code samples sections small and succinct

Don't write a whole application as a code sample in the documentation comment. Make sure you mark it with the apporpriate doc tag.

DO

class Klass {

    /**
     * @example
     * ```html
     * <igx-component [animationSettings]="mySettings">...</igx-component>
     * ```
     */
    @Input()
    public animationSettings: AnimationSettings;
}

AVOID

class Klass {
    /**
     * ```typescript
     *  import { slideInLeft, slideOutRight } from 'igniteui-angular';
     *  ...
     *  myCustomAnimationObject = {
     *      openAnimation: slideInLeft,
     *      closeAnimation: slideOutRight
     * };
     * ```html
     *  <igx-component [animationSettings]="mySettings">
     *  ...
     *  </igx-component>
     * ```
     */
    @Input()
    public animationSettings: AnimationSettings;
}

As a general rule every public API must be sufficiently documented. These include classes, enumerations, interfaces, etc.

/**
 * Avatar provides a way to display an image, icon or initials to the user.
 *
 * @igxModule IgxAvatarModule
 *
 * @igxParent IgxListComponent
 *
 * @igxTheme igx-avatar-theme, igx-icon-theme
 *
 * @igxKeywords avatar, profile, picture, initials
 *
 * @igxGroup presentation
 *
 * @remarks
 * The Ignite UI Avatar provides an easy way to add an avatar icon to your application.
 * This icon can be an image, someone's initials or a material icon from the google material icon set.
 *
 * @example
 * ```html
 * <igx-avatar initials="MS" roundShape="true" size="large">
 * </igx-avatar>
 * ```
 *
 * @example
 * ```html
 * <igx-avatar img="pic.jpg"></igx-avatar>
 * ```
 */
@Component({
    selector: 'igx-avatar',
    templateUrl: 'avatar.component.html'
})
export class IgxAvatarComponent {}

Metadata tags

Tag	Description
igxModule	Denotes the NgModule exporting the decorated class
igxParent	Denotes the parent component (if any)
igxTheme	A list of all the SASS mixins responsible for theming the widget
igxKeywords	A list of tags used as a metadata for searching a specific behavior
igxGroup	Marketing group name of the component/directive
remarks
example