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() {
        ...
    }
}

Add @inheritdoc to public fields in classes implementing interfaces OR if these are inherited and overridden public fields.

This allows comments from interfaces to show in classes in TypeDoc API documentation.

DO

  /** @inheritdoc */
  public settings: PositionSettings;

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 appropriate 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

Generally, you can make use of tags supported by TSDoc/TypeDoc

Below is a summary of the most common ones as well as our custom defined igx- prefixed tags, broken down by usage.

General

Tag	Description
remarks	Additional information following the brief "summary" section
example	Code section demonstrating the usage of the class/component/API
hidden	Hide from generated API output. Often combined with `@internal`
internal	Internal API can be stripped from compiled d.ts definitions. DO NOT apply to `ngModule`-s.
deprecated	Mark class or API as deprecated. Apply alongside deprecation decorator

Note: Deprecation practices and period - we strictly follow Angular on both, when an API or a feature is deprecated, it will still be present in the next two major releases. After that, deprecated APIs and features will be candidates for removal.

Angular decorated classes - Component/Directive/Injectable/Pipe

This applies to classes exposed as public API and intended for stand-alone use.

Tag	Description
igxModule	Denotes the `NgModule` exporting the decorated class
igxKeywords	A list of tags used as a metadata for searching a specific behavior
igxGroup	Marketing group name of the component/directive

Component/Directive only

Tag	Description
igxParent	Denotes the parent component (if any)
igxTheme	A list of all the SASS mixins responsible for theming the widget

Methods

Tag	Description
param	Per-parameter description - `@param <name> <decr>`
returns	Describe the return result of the method

Properties

Tag	Description
igxFriendlyName	Optional friendly name in case the actual property name is not clear or is too specific/obscure/technical. E.g. `bgColor` -> `Background color`, `src` -> `Image URL`