From 647eb8e318f1ed1e3ec18505ea4df57025e6ffd5 Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Fri, 29 Nov 2024 20:40:05 +0100 Subject: update contributing.md --- contributing.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'contributing.md') diff --git a/contributing.md b/contributing.md index 0a90e86..b0f623b 100644 --- a/contributing.md +++ b/contributing.md @@ -17,6 +17,8 @@ that you can click on to open them. working/compiling version of the project - Pull requests for new code include either automated tests for the new code or an explanation as to why the code can not (reliably) be tested +- Non-bugfix pull requests must be approved by at least 2 reviewers before being + merged + - 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). + + - 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). + + > [!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. # Libraries -- cgit v1.2.3 From 47cd8240013cc10682cdfacd39f5988e97b862cc Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 4 Dec 2024 12:57:05 +0100 Subject: update contributing.md --- contributing.md | 66 ++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 49 insertions(+), 17 deletions(-) (limited to 'contributing.md') 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.
GoodBad
```cpp + void Foo::bar() { } + void Foo::set_value(int value) { this->value = value; + this->bar(); } ``` ```cpp + void Foo::bar() { } + void Foo::set_value(int new_value) { value = new_value; + bar(); } ```
@@ -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 -
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; ```
-- 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. - - - 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). - - - 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). - - > [!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) -- cgit v1.2.3 From 210800c5fa71460d9cbcfff808a62cc07e0fdb7a Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Wed, 4 Dec 2024 14:01:01 +0100 Subject: fix namespace type references + update contributing.md --- Doxyfile | 4 ++-- contributing.md | 15 +++++++++++---- src/doc/index.dox | 7 +++++++ src/doc/layout.xml | 10 +++++----- src/doc/style.css | 6 +++--- 5 files changed, 28 insertions(+), 14 deletions(-) (limited to 'contributing.md') diff --git a/Doxyfile b/Doxyfile index f2714cd..07c86d1 100644 --- a/Doxyfile +++ b/Doxyfile @@ -17,11 +17,10 @@ GENERATE_LATEX = NO LAYOUT_FILE = src/doc/layout.xml TAB_SIZE = 2 -HTML_INDEX_NUM_ENTRIES = 2 +HTML_INDEX_NUM_ENTRIES = 999 HTML_EXTRA_STYLESHEET = src/doc/style.css SHOW_HEADERFILE = NO -USE_MDFILE_AS_MAINPAGE = ./readme.md REPEAT_BRIEF = NO EXTRACT_STATIC = YES @@ -29,6 +28,7 @@ HIDE_UNDOC_NAMESPACES = YES HIDE_UNDOC_CLASSES = YES QUIET = YES +WARNINGS = NO # set these to NO for user-only docs INTERNAL_DOCS = YES diff --git a/contributing.md b/contributing.md index 9f22c60..7dedaa7 100644 --- a/contributing.md +++ b/contributing.md @@ -983,18 +983,25 @@ following format: - 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) - - *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 +-
+ 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. + + + ``` + \note This page builds on top of the example shown in \ref feature_script + ``` +
- 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. diff --git a/src/doc/index.dox b/src/doc/index.dox index 5ec7889..7796f34 100644 --- a/src/doc/index.dox +++ b/src/doc/index.dox @@ -8,3 +8,10 @@ Welcome to the documentation for the crêpe game engine. \see feature */ + +/** + +\namespace crepe +\brief Engine namespace + +*/ diff --git a/src/doc/layout.xml b/src/doc/layout.xml index fb4cc0c..6336655 100644 --- a/src/doc/layout.xml +++ b/src/doc/layout.xml @@ -11,7 +11,7 @@ - + @@ -56,10 +56,10 @@ - - + + @@ -102,11 +102,12 @@ + - + @@ -119,7 +120,6 @@ - diff --git a/src/doc/style.css b/src/doc/style.css index daabd39..c12240c 100644 --- a/src/doc/style.css +++ b/src/doc/style.css @@ -1,6 +1,6 @@ #titlearea, -address { - display: none; -} +address, +a[href="namespaces.html"] +{ display: none; } h2.groupheader { margin-top: revert; } -- cgit v1.2.3