aboutsummaryrefslogtreecommitdiff
path: root/contributing.md
diff options
context:
space:
mode:
authorJAROWMR <jarorutjes07@gmail.com>2024-12-05 21:10:07 +0100
committerJAROWMR <jarorutjes07@gmail.com>2024-12-05 21:10:07 +0100
commit9604616001ac273f2c966c3c829638e905def7bf (patch)
tree7e958c2b658a4dbc9e79068d7309513efa928937 /contributing.md
parent018a451051669506be447aa925ecb6a9f5aaf418 (diff)
parent1f4e961d7f9d6887c807cac1a362f2d178b0860b (diff)
merge with master and keypressed added to game
Diffstat (limited to 'contributing.md')
-rw-r--r--contributing.md56
1 files changed, 56 insertions, 0 deletions
diff --git a/contributing.md b/contributing.md
index b0f623b..7dedaa7 100644
--- a/contributing.md
+++ b/contributing.md
@@ -635,15 +635,21 @@ that you can click on to open them.
</summary><table><tr><th>Good</th><th>Bad</th></tr><tr><td>
```cpp
+ void Foo::bar() { }
+
void Foo::set_value(int value) {
this->value = value;
+ this->bar();
}
```
</td><td>
```cpp
+ void Foo::bar() { }
+
void Foo::set_value(int new_value) {
value = new_value;
+ bar();
}
```
</td></tr></table></details>
@@ -868,6 +874,8 @@ that you can click on to open them.
# Documentation
+[Doxygen commands](https://www.doxygen.nl/manual/commands.html)
+
- All documentation is written in U.S. English
- <details><summary>
Doxygen commands are used with a backslash instead of an at-sign.
@@ -953,6 +961,52 @@ that you can click on to open them.
Foo & operator=(Foo &&) = delete;
```
</td></tr></table></details>
+- Do not use markdown headings in Doxygen
+
+## Documenting features
+
+Engine features are small 'building blocks' that the user (game developer) may
+reference when building a game with the engine. Features do not necessarily map
+1-1 to engine components or systems. If a component or system has a single,
+distinct feature it should be named after that feature, not the component or
+system itself.
+
+The sources for these pages are located under `src/doc/feature/`, and have the
+following format:
+
+- A feature description which explains—
+ - the purpose and function of the feature (focus on what it enables or
+ achieves for the user)
+ - additional information about when to implement the feature, such as specific
+ use cases or scenarios
+- A list of 'see also' references to relevant classes and/or types
+- A **minimal** example to demonstrate how the feature is used. The example
+ should be written such that the following is clear to the reader:
+ - Which headers need to be included to utilize the feature
+ - *Why* the example works, not what is happening in the example
+ - Where is this code supposed to be called (e.g. inside scene/script
+ functions)
+ - Which restrictions should be kept in mind (e.g. copy/move semantics, max
+ component instances, speed considerations)
+
+Features should be documented as clear and concise as possible, so the following
+points should be kept in mind:
+
+- <details><summary>
+ If a page expands on an example from another page, directly reference the
+ other page using a cross-reference (`\ref`) in a `\note` block at the top of
+ the page.
+ </summary>
+
+ ```
+ \note This page builds on top of the example shown in \ref feature_script
+ ```
+ </details>
+- When explaining the usage of specific functions, qualify them such that
+ Doxygen is able to add a cross-reference or manually add a reference using the
+ `\ref` command.
+- Users will likely copy-paste examples as-is, so do this yourself to check if
+ the example code actually works!
# Libraries
@@ -960,4 +1014,6 @@ that you can click on to open them.
subdirectory
- When adding new submodules, please set the `shallow` option to `true` in the
[.gitmodules](./.gitmodules) file
+- When adding new libraries, please update the library version table in
+ [readme\.md](./readme.md)