Document Tree
Document Properties
Kbid
308E30
Last Modified
21-Dec-2023
Added to KB
18-Apr-2023
Public Access
Everyone
Status
Online
Doc Type
Guidelines
Product
Intershop Progressive Web App
Guide - Intershop Progressive Web App - Code Documentation

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>
 */

Warning

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.

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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.