Skip to content

Documentation Guidelines

IvayloG edited this page Mar 31, 2020 · 6 revisions

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
   * ...
   */
  clone(): IPositionStrategy {
    return Util.cloneInstance(this);
  }

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

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
Clone this wiki locally