Related Github Documents
Document Properties
Kbid2944H5
Last Modified08-Jun-2020
Added to KB18-Jun-2020
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
ProductIntershop Progressive Web App

Guide - Intershop Progressive Web App - Code Documentation

Code Documentation

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

For documentation, the tsconfig.app.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 sortings 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 [product]="product"></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 pricise 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.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets