docs(contributing): jsdocs section

CONTRIBUTING.md

@@ -71,6 +71,135 @@ get cat() {
 }
 ```
 
+## JSDocs
+
+JSDoc are comments above any code structure (variable, function, class, etc.) that begin with `/**` and end with `*/`. Multiline comments start (if not being the start or end line) with a `*`.
+For more info checkout [jsdoc.app](https://jsdoc.app/about-getting-started.html).
+
+JSDoc will be read and automatically processed by `generate:api-docs` and therefore need to follow some project conventions. Other standards are in place because we think they provide a better code quality in general.
+
+> We use eslint-plugin-jsdoc to test for basic styling and sorting of doc-tags.
+
+This is in place so all JSDoc tags will get sorted automatically, so you don't have to bother with it. This also means that most rules in this section can get auto fixed by the eslint formatter.
+
+> JSDocs should always be multiline
+
+While single line JSDoc are technically valid, we decided to follow this rule since it makes changes in the git diff much more clear and easier to understand.
+
+<table>
+<tr>
+<th>Do</th>
+<th>Dont</th>
+</tr>
+<tr>
+<td>
+
+```ts
+/**
+ * This is a good JSDoc description.
+ */
+function foo() {
+  // implementation
+}
+```
+
+</td>
+<td>
+
+```ts
+/** This is a bad JSDoc description. */
+function foo() {
+  // implementation
+}
+```
+
+</td>
+</tr>
+</table>
+
+> Everything that can be accessed directly by a user should have JSDoc.
+
+This rule is aimed to target anything that is exported from the faker library. This includes types, interfaces, functions, classes and variables. So if you introduce anything new that is not internal, write JSDoc for it.
+
+> If a `@param` has a default value, it needs to be mentioned at the end of the sentence.
+
+```ts
+/**
+ * This is a good JSDoc description.
+ *
+ * @param bar this is a parameter description. Defaults to `0`.
+ */
+function foo(bar: number = 0) {
+  // implementation
+}
+```
+
+> If a function can throw an error (FakerError) you have to include the `@throws` tag with an explanation when an error could be thrown
+
+```ts
+/**
+ * This is a good JSDoc description.
+ *
+ * @param bar this is a parameter description. Defaults to `0`.
+ *
+ * @throws If bar is negative.
+ */
+function foo(bar: number = 0) {
+  // implementation
+}
+```
+
+> Sentences should always end with a period.
+
+This rule ensures minimal grammatical correctness in the comments and ensures that all comments look the same.
+
+> Different tags have to be separated by an empty line.
+
+This rule improves the comments readability by grouping equivalent tags and making them more distinguishable from others.
+
+<table>
+<tr>
+<th>Do</th>
+<th>Dont</th>
+</tr>
+<tr>
+<td>
+
+```ts
+/**
+ * This is a bad JSDoc block, because it has no linebreaks between sections.
+ * @param bar The first argument.
+ * @param baz The second argument.
+ * @example foo(1, 1) // [1, 1]
+ * @example foo(13, 56) // [13, 56]
+ */
+function foo(bar: number, baz: number): [number, number] {
+  // implementation
+}
+```
+
+</td>
+<td>
+
+```ts
+/**
+ * This is a good JSDoc block, because it follows the Faker preferences.
+ *
+ * @param bar The first argument.
+ * @param baz The second argument.
+ *
+ * @example foo(1, 1) // [1, 1]
+ * @example foo(13, 56) // [13, 56]
+ */
+function foo(bar: number, baz: number): [number, number] {
+  // implementation
+}
+```
+
+</td>
+</tr>
+</table>
+
 ## Developing the docs
 
 Before running the docs, build the Faker dist, it's used inside of certain routes.