From 8e7992046ca20b81413b5559f9c52c0740d64563 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Wieland=20Sch=C3=B6bl?=
 <wieland.schoebl@campus.tu-berlin.de>
Date: Wed, 3 Jul 2019 14:06:46 +0200
Subject: [PATCH] docs: improved docs for comments

---
 project-docs/workflow/DOCUMENTATION.md | 31 ++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/project-docs/workflow/DOCUMENTATION.md b/project-docs/workflow/DOCUMENTATION.md
index 98447000..437284e6 100644
--- a/project-docs/workflow/DOCUMENTATION.md
+++ b/project-docs/workflow/DOCUMENTATION.md
@@ -36,6 +36,37 @@ async get<T>(key: string): Promise<T> {
   return entry;
 }
 ```
+### Inline Comments `//`
+
+* Start inline comments with a lowercase letter and a space after the `//`
+* Place the comment above the line that it is referencing
+```typescript
+// lorem ipsum
+const lorem;
+```
+
+### Doc Comments `/**`
+
+* Start with a capital letter
+* Keep the first line short
+* The first line should not end with a period, nor should it consist of multiple sentences
+* The first line should be easily scannable
+* If you want to comment more than one line, do a short summary in the first line, then continue after a blank line with the more detailed description
+* Document all parameters in functions using `@param`
+* `@param` must not contain a type annotation, just `@param name description`
+* Do not include `@return`, as it is redundant information
+```typescript
+/**
+ * Short summary of the function, without a period
+ * 
+ * This is a very long description, that could never possibly fit on one line, nor could it
+ * be read in a short amount of time. Because we can use multiple sentences here, we can actually
+ * use a period.
+ *
+ * @param foo This parameter does something
+ */
+function fun(foo: number): Foo {
+```
 
 ## `CONTRIBUTING.md`