Documentation

Every projects need a README.md as a standardized entry of information about the scope of a project and how to install and execute it.

Inline (code) documentation

Code is annotated with TypeDoc, which then can be used to generate complete documentations of the API of the code.

Guidelines

Please follow these guidelines to reduce redundance:

The purpose of inline documentation is to explain what the line of code actually does without explaining syntax or external references. Example:

// extend the template by the properties of the base template
templateBase.properties = mergeObjects(
  templateBase.properties,
  templates['base.template.json'].mappings._default_.properties
);

Follow the recommendations of typedoc, because it is used to generate documentation. Do not denote the types again in the documentation (@param and @returns), because they are already "documented" in the code itself. Example:

/**
 * Gets a value from the storage using the provided key
 *
 * @param key Unique identifier of the wanted resource in storage
 */
async get<T>(key: string): Promise<T> {
  const entry = await this.storage.get(key);
  if (!entry) {
    throw new Error('Value not found.');
  }
  return entry;
}

`CONTRIBUTING.md`

Every project can have a CONTRIBUTING.md which explains how to contribute to the project either just by issues or code contributions.

Issue templates

The path .gitlab/issue_templates can contain markdown files which act as templates for issues. These are available as an options during issue creation and just have to be filled by the creator of the issue. They act as orientation which information need sto be provided.

Further resources

GitLab issue templates

1.9 KiB Raw Blame History