docs: Doxygen usage & guidelines (#7)

* 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

* 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.

* 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.

* 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.

* 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.

Author: aZaamBie

docs/style/comments.md

@@ -41,6 +41,140 @@ 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
+- **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 | `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.`|
+    | ✅ Good| `The function modifies the integer.`|
+
+- Write in Third Person instead of First Person:
+
+    |  |  |
+    |--|--|
+    | ❌ No usage of: <em>I, me, we</em>. | `# I calculate the average here.` <br> `# We initialize the module`|
+    | ✅ Use Third person| `Calculates the average of the values.`<br>`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 [C++ only]:**
+
+    /**
+     * @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 Documentation:**
+
+- 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#:
+
+        /// <summary>
+        /// Calculates the sum of two integers.
+        /// </summary>
+        /// <param name="left">The first integer operand.</param>
+        /// <param name="right">The second integer operand.</param>
+        /// <returns>The sum of the two integers.</returns>
+        public static int Add(int left, int right)
+        {
+            return left + right;
+        }
+
+**Class Documentation:**
+
+- 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<T>
+        {
+            // Class implementation
+        }
+
+- C#:
+
+        /// <summary>
+        /// A summary about this class.
+        /// </summary>
+        /// <remarks>
+        /// These remarks would explain more about this class.
+        /// In this example, these comments also explain the
+        /// general information about the derived class.
+        /// </remarks>
+        public class MainClass
+        {
+        }
+
+- For more examples, look here: <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/examples>
+
 ---
 
 ## Discouraged Comment Styles