update contributing.md

1 files changed, 49 insertions, 17 deletions

diff --git a/contributing.md b/contributing.md
index 85e29bb..9f22c60 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,23 +961,45 @@ that you can click on to open them.
   Foo & operator=(Foo &&) = delete;
   ```
   </td></tr></table></details>
-- Features are described in the Doxygen Feature Tab (in this order):
-  - A feature description should explain the purpose and function of the feature,
-    focusing on what it enables or achieves for the gamedeveloper.
-  - Include additional information about when to implement the feature,
-    such as specific use cases or scenarios.
-  - Provide an example to demonstrate how gamedevelopers can enable or use the feature.
-    <!-- add example -->
-  - If the current feature depends on or reuses a previous feature,  
-    include a link to that feature from the current feature (backward link, if applicable).
-    <!-- add example -->
-  - If the current feature depends on or reuses a previous feature,  
-    include a link from the previous feature to the current feature (forward link, if applicable).
-    <!-- add example -->
-  > [!NOTE]
-  > A feature is almost never a component, system or large part of the engine.
-  > If a component or system has a single,
-  > distinct feature it should be named after that feature, not the component or system itself.
+- 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
+  - Where is this code supposed to be called (e.g. inside scene/script
+    functions)
+  - *Why* the example works, not what is happening in the example
+  - 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:
+
+- If a page expands on an example from another page, directly reference the
+  other page using a cross-reference (`\ref`) instead of writing a larger
+  example
+- 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
 
@@ -977,4 +1007,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)