# Documentation

Every projects need a `README.md` as a standardized entry of information about the scope of a [project](PROJECT.md) and how to install and execute it. 

## Inline (code) documentation

Code is annotated with [TypeDoc](https://typedoc.org/), 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: 

```typescript
// 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](http://typedoc.org/guides/doccomments/) 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. Beispiel:

```typescript
/**
 * 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](https://gitlab.com/help/user/project/description_templates.md)