For our Intershop Progressive Web App, Compodoc is used as documentation package.

For documentation, the tsconfig.doc.json file is used as configuration file.
The output folder for the documentation is set to /docs/compodoc.

We use an own styling theme based on the theme 'readthedocs' provided by Compodoc.
The style.css file of the theme can be found in /docs/theme.

Examples for the comment styling pattern can be found here: TypeDoc - DocComments.

Usage

Generate Code Documentation

Generate Code Documentation

npm run compodoc

The generated documentation can be called by /docs/compodoc/index.html.

Serve Generated Documentation with Compodoc

Serve Generated Documentation with Compodoc

npm run compodoc:serve

Documentation is generated at /docs/compodoc (output folder).
The local HTTP server is launched at http://localhost:8080.

Comments

General Information

The JSDoc comment format is used for general information.

Use this format to describe components, modules, etc., but also methods, inputs, variables and so on.

Example for General Description

/**
 * The Product Images Component
 */

JSDoc Tags

Currently Compodoc supports the following JSDoc tags :

• @returns
• @param
• @link
• @example

Example for parameter and return values

/**
 * Get products for a given search term respecting pagination.
 * @param searchTerm    The search term to look for matching products.
 * @param page          The page to request (1-based numbering)
 * @param sortKey       The sortKey to sort the list, default value is ''.
 * @returns             A list of matching Product stubs with a list of possible sorting and the total amount of results.
 */
searchProducts(
  searchTerm: string,
  page: number,
  sortKey?: string
): Observable<{ products: Product[]; sortKeys: string[]; total: number }> {

Example for links and implementation examples

/**
 * The Product Images Component displays carousel slides for all images of the product and a thumbnails list as carousel indicator.
 * It uses the {@link ProductImageComponent} for the rendering of product images.
 *
 * @example
 * <ish-product-images></ish-product-images>
 */

⚠️ Indentation Warning
TypeScript has an internal margin for new lines. If you want to keep a level of indentation, put a minimum of 13 space characters as shown in the example:

Example with Indentation Keeping

/**
 * @example
 * <div class="form-group has-feedback" [formGroup]="form" [ishShowFormFeedback]="formControl">
 *               <input
 *                 [type]="type"
 *                 class="form-control">
 *               <ish-form-control-feedback [messages]="errorMessages" [control]="formControl"></ish-form-control-feedback>
 * </div>
 */

New lines are created inside a comment with a blank line between two lines:

Comments with New Lines

/**
 * First line
 *
 * Second line
 */

/**
 * First line
 * Behind first line, produces only one line
 */

⚠️ Document only if documentation is needed!

This is not a project with obligatory documentation, so: Do not document the obvious! For example, if behavior and requirements can be implied by a method signature, no additional documentation is needed.
Instead pay attention to useful names.
If you cannot find a precise name for your variable or method, maybe this is a sign that too much is done here and it would be better to refactor instead.

However, there are some cases where documentation is recommended:

• Technical background required,

• Restraints on method arguments, that cannot be inferred by the method signature alone,

• Tricky parts where some degree of magic is happening (especially useful as in-line documentation),

• Class documentation for exported shared components.