Skip to content

Latest commit

 

History

History
106 lines (81 loc) · 3.03 KB

code-documentation.md

File metadata and controls

106 lines (81 loc) · 3.03 KB

Code Documentation

The JSDoc comment format is used for general information.

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

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

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.