Documenting Code

Documentation Syntax

The list of accepted tags and formats can be found here. The following guide consists of examples in documenting different scenarios.

Properties

Inputs, outputs and other flags/variables should be documented in a uniform fashion. Typically, one line is enough for these.

Inputs should be tagged as such.

/** @Input Whether the alert is dismissible. */
@Input()
dismissible: boolean = true;

Outputs should be tagged as such.

/** @Output Event fired when the alert is dismissed. */
@Output()
onDismiss: EventEmitter<undefined> = new EventEmitter<undefined>();

Private properties do not need to be documented.

Properties that are not private nor inputs/outputs should be documented.

Functions

Functions should be documented if they are not private.

/**
 * Opens an alert component with a content of type TemplateRef, Component Type or String.
 * @param content Content of the alert component.
 * @param alertConfig Configuration of the alert component.
 */
public open(content: TemplateRef<any> | Type<any> | string, alertConfig: AlertConfig = new AlertConfig()): AlertRef {
    ...
    ...
}

Classes

Classes should be given a quick explanation with any relevant information the user would need.

/**
 * Configuration for opening an alert with the AlertService.
 */
export class AlertConfig {
    ...
    ...
}

Components

These can be approached in the same way as classes.

Optionally, you can include a quick snippet of code to show how to use the component.

Directives

Directives are treated the same as classes or components, but in the case of directives that have very little content, a code example is mandatory.

/**
 * Directive that applies fundamental modal styling to a header.
 *
 * ```html
 * <h1 fd-modal-title>Modal Title</h1>
 * ```
 */
@Directive({
    selector: '[fd-modal-title]'
})
export class ModalTitleDirective {
    ...
    ...
}

Exclusions

Functions or properties that the user will not use should be tagged as @hidden if they are not private.

In particular, for Angular, constructors do need bring anything useful to a documentation. As such, it is better to tag them as hidden.

/** @hidden */
@HostBinding('class.fd-button--light')
lightButton = true;