Documenting Code - SAP/fundamental-ngx GitHub Wiki

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

For development, you will need to run npm run compile-typedoc to see the API files. They are not hot-reloaded.

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

Inputs should always be documented.

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

Outputs should always be documented.

/** 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, unless they should not be used by the user.

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

Documenting hooks serves no purpose to the user. These should be tagged with @hidden unless they can be shown to be useful to a user of the library.

/** @hidden */
ngOnInit(): void {
    ...
    ...
}

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

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.

/**
 * Applies fundamental layout and styling to the contents of a modal footer.
 *
 * ```html
 * <fd-modal-footer>
 *     <button>Do action</button>
 * </fd-modal-footer>
 * ```
 */
@Component({
    selector: 'fd-modal-footer',
    templateUrl: './modal-footer.component.html'
})
export class ModalFooterComponent {
    ...
    ...
}

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

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 */
constructor(private elRef: ElementRef) {}

HostBindings are equivalently useless to document, generally. There are exceptions here of course.

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