From 0bc43718e665f073a04b19e5b725d6393a644590 Mon Sep 17 00:00:00 2001 From: aZamBie <53663013+aZaamBie@users.noreply.github.com> Date: Mon, 26 Jan 2026 22:27:56 +0200 Subject: [PATCH 1/5] Doxygen: started the guidelines I started writing the guidelines for the Doxygen section. Focusing on where to use them, how to write them, core structure and grammar, and giving example templates for comments to be used in File header and above each method. To-do: clean up --- docs/style/comments.md | 66 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/docs/style/comments.md b/docs/style/comments.md index b7514f7..0e4c3cc 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -40,7 +40,71 @@ Example: | **DEPRECATED** | as-of-date(dd/mm/yyyy) | Mark an API or function as deprecated. | `// DEPRECATED(19/06/2025): Replaced this function with Foo()` | | **WTF** | - | Identify confusing or unexpected behavior requiring investigation. *(Use sparingly.)* | `// WTF: Behavior differs between debug and release builds` | ---- +--- + +## Doxygen Guidelines + +### Where to use? + +- At the header of every file, explaining: + - Filename + - Brief description + - Author + - Date of Creation +- Above every method: + - Describing the purpose briefly, in one line + - Then you can describe the method in more detail. (What algorithms were used, unique decisions made, any wildcards.) + - Describe the parameter(s) and result. + +### Comment style & Format (How to write?) + +**Core:** +- Present tense + | | | + |--|--| + | ❌ Bad | `x does this thing to y. ` | + | ✅ Good| `Sorts through array `| +- Active voice: *Subject + Verb + Object* + | | | + |--|--| + | ❌ Bad | `The integer was modified by the function. ` | + | ✅ Good| `The function modifies the integer.`| +- Write in Third Person instead of First person: + - ❌ No: I, me, we + - `# I retrieve the label's text via calling the method` + - ✅ Rather use third person + - `# The label is retrieved via the method's call.` + + +**File headers:** + + /** + * @file filename.cpp + * @brief Brief description of file purpose + * @author John Doe (optional) + * @date 2024-01-15 + * + * Detailed description of file contents, context, and usage... + * Can span multiple lines... + * + * @NOTE: ... Important notes about this file + * @WARNING: ... Any warnings for developers + */ + +**Method template:** + + /** + * @brief One-line description of function purpose + * + * Detailed description including algorithm, edge cases, + * performance characteristics, etc. + * + * @param param1 Description of first parameter + * @param param2 Description of second parameter + * @return Description of return value + * / + +--- ## Discouraged Comment Styles From 8159970808aceebe5fa3f771314038b1f1b6da26 Mon Sep 17 00:00:00 2001 From: Azaam <53663013+aZaamBie@users.noreply.github.com> Date: Mon, 2 Feb 2026 17:34:42 +0200 Subject: [PATCH 2/5] Improved grammar + small addition I improved the grammar for my section. Also added another 1-2 rules in the "Writing style guidelines". Added more tables with the good and bad examples. --- docs/style/comments.md | 75 ++++++++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 21 deletions(-) diff --git a/docs/style/comments.md b/docs/style/comments.md index 0e4c3cc..784c2b1 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -44,40 +44,57 @@ Example: ## Doxygen Guidelines -### Where to use? +### 📍 Where to use? -- At the header of every file, explaining: +- At the **header** of every file, explaining: - Filename - - Brief description - - Author + - Brief description of file's purpose and contents. + - Author(s) - Date of Creation -- Above every method: - - Describing the purpose briefly, in one line - - Then you can describe the method in more detail. (What algorithms were used, unique decisions made, any wildcards.) - - Describe the parameter(s) and result. - -### Comment style & Format (How to write?) - -**Core:** +- **Above** every **Method**, describing: + - The purpose briefly, in one line + - The method in more detail. (What algorithms were used, unique decisions made.) + - The parameter(s) and result. +- **Class/Struct** documenation: + - Brief class description + - Detailed usage information. + - Template parameters. + - Important Member relationships + +### :writing_hand: Writing Style guidelines + +**Grammar & Tone:** - Present tense | | | |--|--| - | ❌ Bad | `x does this thing to y. ` | - | ✅ Good| `Sorts through array `| + | ❌ Bad | `The function will sort the array ` | + | ✅ Good| `Sorts the array using quicksort. `| + - Active voice: *Subject + Verb + Object* | | | |--|--| - | ❌ Bad | `The integer was modified by the function. ` | + | ❌ Bad | `The integer is modified by the method. ` | | ✅ Good| `The function modifies the integer.`| -- Write in Third Person instead of First person: - - ❌ No: I, me, we - - `# I retrieve the label's text via calling the method` - - ✅ Rather use third person - - `# The label is retrieved via the method's call.` +- Write in Third Person instead of First Person: + + | | | + |--|--| + | ❌ No usage of: I, me, we. | `# I calculate the average here.`
`# We initialize the module` | + | ✅ Use Third person| `Calculates the average of the values.`
`Initializes the communication module.` | + +- Be direct and concise, +- Start summaries with a verb: + | | | + |--|--| + | ❌ Bad | `This function is responsible for performing the task of data validation.` | + | ✅ Good| `Validates input data format.`| + +### TEMPLATES **File headers:** + /** * @file filename.cpp * @brief Brief description of file purpose @@ -91,7 +108,7 @@ Example: * @WARNING: ... Any warnings for developers */ -**Method template:** +**Method Documentation:** /** * @brief One-line description of function purpose @@ -104,6 +121,22 @@ Example: * @return Description of return value * / +**Class Documentation:** + + /** + * @class ClassName + * @brief Brief description of class purpose + * + * Detailed explanation of class responsibilities, usage patterns, + * and important design decisions. + * + * @param Description of template parameter requirements + */ + template + class ClassName { + // Class implementation + }; + --- ## Discouraged Comment Styles From 6d91d7d0e14252468542fc6579ff4ac96e3ed2ae Mon Sep 17 00:00:00 2001 From: Azaam <53663013+aZaamBie@users.noreply.github.com> Date: Mon, 2 Feb 2026 18:33:33 +0200 Subject: [PATCH 3/5] Improved comment examples The examples in the Doxygen comment guidelines have been updated and improved. I placed a link to the official C# XML example page. --- docs/style/comments.md | 82 +++++++++++++++++++++++++++++------------- 1 file changed, 57 insertions(+), 25 deletions(-) diff --git a/docs/style/comments.md b/docs/style/comments.md index 784c2b1..f0d491d 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -92,7 +92,7 @@ Example: ### TEMPLATES -**File headers:** +**File headers [C++ only]:** /** @@ -109,33 +109,65 @@ Example: */ **Method Documentation:** - - /** - * @brief One-line description of function purpose - * - * Detailed description including algorithm, edge cases, - * performance characteristics, etc. - * - * @param param1 Description of first parameter - * @param param2 Description of second parameter - * @return Description of return value - * / +- C++: + + /** + * @brief One-line description of function purpose + * + * Detailed description including algorithm, edge cases, + * performance characteristics, etc. + * + * @param param1 Description of first parameter + * @param param2 Description of second parameter + * @return Description of return value + * / + +- C#: + + /// + /// Calculates the sum of two integers. + /// + /// The first integer operand. + /// The second integer operand. + /// The sum of the two integers. + public static int Add(int left, int right) + { + return left + right; + } **Class Documentation:** - /** - * @class ClassName - * @brief Brief description of class purpose - * - * Detailed explanation of class responsibilities, usage patterns, - * and important design decisions. - * - * @param Description of template parameter requirements - */ - template - class ClassName { - // Class implementation - }; +- C++ + + /** + * @class ClassName + * @brief Brief description of class purpose + * + * Detailed explanation of class responsibilities, usage patterns, + * and important design decisions. + * + * @param Description of template parameter requirements + */ + public class ClassName + { + // Class implementation + } + +- C#: + + /// + /// A summary about this class. + /// + /// + /// These remarks would explain more about this class. + /// In this example, these comments also explain the + /// general information about the derived class. + /// + public class MainClass + { + } + +- For more examples, look here: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/examples --- From d0afd2c2f6468466d3c6d58e26acb2d19d5c0ee9 Mon Sep 17 00:00:00 2001 From: Azaam <53663013+aZaamBie@users.noreply.github.com> Date: Wed, 4 Feb 2026 21:26:16 +0200 Subject: [PATCH 4/5] Fixing linting issues These are the following changes made to suit the Linter's standards: - Replaced tab-indents with spacebar-indents. - Removed trailing whitespaces - Table: kept a line free/empty above and below each table. - Added arrow tags <>, to every bare URL used. --- docs/style/comments.md | 54 +++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/docs/style/comments.md b/docs/style/comments.md index f0d491d..a976698 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -40,57 +40,62 @@ Example: | **DEPRECATED** | as-of-date(dd/mm/yyyy) | Mark an API or function as deprecated. | `// DEPRECATED(19/06/2025): Replaced this function with Foo()` | | **WTF** | - | Identify confusing or unexpected behavior requiring investigation. *(Use sparingly.)* | `// WTF: Behavior differs between debug and release builds` | ---- +--- ## Doxygen Guidelines ### 📍 Where to use? - At the **header** of every file, explaining: - - Filename - - Brief description of file's purpose and contents. - - Author(s) - - Date of Creation + - Filename + - Brief description of file's purpose and contents. + - Author(s) + - Date of Creation - **Above** every **Method**, describing: - - The purpose briefly, in one line - - The method in more detail. (What algorithms were used, unique decisions made.) - - The parameter(s) and result. + - The purpose briefly, in one line + - The method in more detail. (What algorithms were used, unique decisions made.) + - The parameter(s) and result. - **Class/Struct** documenation: - - Brief class description - - Detailed usage information. - - Template parameters. - - Important Member relationships + - Brief class description + - Detailed usage information. + - Template parameters. + - Important Member relationships -### :writing_hand: Writing Style guidelines +### :writing_hand: Writing Style guidelines **Grammar & Tone:** + - Present tense - | | | - |--|--| - | ❌ Bad | `The function will sort the array ` | - | ✅ Good| `Sorts the array using quicksort. `| + + | | | + |--|--| + | ❌ Bad | `The function will sort the array.`| + | ✅ Good| `Sorts the array using quicksort.`| - Active voice: *Subject + Verb + Object* + | | | |--|--| - | ❌ Bad | `The integer is modified by the method. ` | + | ❌ Bad | `The integer is modified by the method.`| | ✅ Good| `The function modifies the integer.`| -- Write in Third Person instead of First Person: +- Write in Third Person instead of First Person: | | | |--|--| - | ❌ No usage of: I, me, we. | `# I calculate the average here.`
`# We initialize the module` | - | ✅ Use Third person| `Calculates the average of the values.`
`Initializes the communication module.` | + | ❌ No usage of: I, me, we. | `# I calculate the average here.`
`# We initialize the module`| + | ✅ Use Third person| `Calculates the average of the values.`
`Initializes the communication module.`| - Be direct and concise, + - Start summaries with a verb: + | | | |--|--| | ❌ Bad | `This function is responsible for performing the task of data validation.` | | ✅ Good| `Validates input data format.`| -### TEMPLATES +### TEMPLATES **File headers [C++ only]:** @@ -109,6 +114,7 @@ Example: */ **Method Documentation:** + - C++: /** @@ -167,9 +173,9 @@ Example: { } -- For more examples, look here: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/examples +- For more examples, look here: ---- +--- ## Discouraged Comment Styles From fa1c5c90ecd04e40e138977ee8f1b5d53bfe84ac Mon Sep 17 00:00:00 2001 From: Azaam <53663013+aZaamBie@users.noreply.github.com> Date: Wed, 4 Feb 2026 21:31:22 +0200 Subject: [PATCH 5/5] More smaller linting fixes This SHOULD be the remaining fixes for the linting issues. I was using 2 spaces for indentation (because md007 tells us to use 2 in the example_) but am now using 4 spaces. --- docs/style/comments.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/style/comments.md b/docs/style/comments.md index a976698..6e23986 100644 --- a/docs/style/comments.md +++ b/docs/style/comments.md @@ -47,19 +47,19 @@ Example: ### 📍 Where to use? - At the **header** of every file, explaining: - - Filename - - Brief description of file's purpose and contents. - - Author(s) - - Date of Creation + - Filename + - Brief description of file's purpose and contents. + - Author(s) + - Date of Creation - **Above** every **Method**, describing: - - The purpose briefly, in one line - - The method in more detail. (What algorithms were used, unique decisions made.) - - The parameter(s) and result. + - The purpose briefly, in one line + - The method in more detail. (What algorithms were used, unique decisions made.) + - The parameter(s) and result. - **Class/Struct** documenation: - - Brief class description - - Detailed usage information. - - Template parameters. - - Important Member relationships + - Brief class description + - Detailed usage information. + - Template parameters. + - Important Member relationships ### :writing_hand: Writing Style guidelines @@ -80,7 +80,7 @@ Example: | ✅ Good| `The function modifies the integer.`| - Write in Third Person instead of First Person: - + | | | |--|--| | ❌ No usage of: I, me, we. | `# I calculate the average here.`
`# We initialize the module`| @@ -99,7 +99,6 @@ Example: **File headers [C++ only]:** - /** * @file filename.cpp * @brief Brief description of file purpose