Merge branch '35-add-how-to-write-the-plugin-doc-to-the-dev-manual' into 'dev'

Resolve "add how to write the plugin doc to the dev manual"

See merge request fusiondirectory/dev-manual!155

source/fusiondirectory/development/documentation/PHPDoc.rst

+.. _phpdoc_guide:
+
+##############################
+PHPDoc Guide for Doxygen Usage
+##############################
+
+This guide explains how to properly document PHP code using PHPDoc comments and generate documentation using `Doxygen <https://www.doxygen.nl/>`_.
+
+.. contents:: Table of Contents
+   :local:
+   :depth: 2
+
+----------------------
+Introduction to PHPDoc
+----------------------
+
+PHPDoc is a standardized way of documenting PHP code using special comment blocks (`/** ... */`).
+Doxygen can parse these comments to generate structured documentation.
+
+**Basic Example:**
+
+.. code-block:: php
+
+   <?php
+   /**
+    * Adds two numbers.
+    *
+    * @param int $a First number.
+    * @param int $b Second number.
+    * @return int Sum of $a and $b.
+    */
+   function add(int $a, int $b): int {
+       return $a + $b;
+   }
+
+-----------------
+PHPDoc Syntax
+-----------------
+
+**General Structure**
+
+A PHPDoc comment starts with `/**` and ends with `*/`. Each line inside the block should start with `*`. The first paragraph is usually a short description, followed by optional tags.
+
+**Example:**
+
+.. code-block:: php
+
+   /**
+    * Short description.
+    *
+    * Detailed description, spanning multiple lines.
+    *
+    * @tagname Type Description
+    */
+
+**Common Tags**
+
+.. list-table:: Common PHPDoc Tags
+   :widths: 15 40 45
+   :header-rows: 1
+
+   * - **Tag**
+     - **Description**
+     - **Example**
+   * - ``@param``
+     - Describes function parameters
+     - ``@param string $name The name of the user.``
+   * - ``@return``
+     - Describes the return value
+     - ``@return bool True on success, false otherwise.``
+   * - ``@var``
+     - Describes class properties
+     - ``@var int $count Number of items.``
+   * - ``@throws``
+     - Documents exceptions thrown by the function
+     - ``@throws Exception If an error occurs.``
+   * - ``@deprecated``
+     - Marks a function/class as deprecated
+     - ``@deprecated Use newFunction() instead.``
+   * - ``@author``
+     - Specifies the author of the code
+     - ``@author John Doe <john@example.com>``
+   * - ``@version``
+     - Specifies version information
+     - ``@version 1.0.0``
+   * - ``@since``
+     - Indicates when a feature was added
+     - ``@since 2.0``
+
+---------------------------
+Documenting Classes & Files
+---------------------------
+
+**Documenting a Class**
+
+.. code-block:: php
+
+   <?php
+   /**
+    * Description of your class user here and potential extensions.
+    */
+   class User {
+       /**
+        * The user's name.
+        *
+        * @var string
+        */
+       private string $name;
+
+       /**
+        * Constructor.
+        *
+        * @param string $name The user's name.
+        */
+       public function __construct(string $name) {
+           $this->name = $name;
+       }
+
+       /**
+        * Gets the user's name.
+        *
+        * @return string The name of the user.
+        */
+       public function getName(): string {
+           return $this->name;
+       }
+   }
+
+-------------------------
+Generating Documentation
+-------------------------
+
+To generate documentation using Doxygen:
+
+1. **Install Doxygen**: Download from `https://www.doxygen.nl/` and install it.
+2. **Create a Doxygen configuration file**: Run:
+
+   .. code-block:: bash
+
+      doxygen -g Doxyfile
+
+3. **Modify the `Doxyfile`**:
+
+   - Set `INPUT` to the PHP source code directory.
+   - Enable `EXTRACT_ALL = YES` to parse all comments.
+   - Set `FILE_PATTERNS = *.php` to only parse PHP files.
+
+4. **Generate the Documentation**:
+
+   .. code-block:: bash
+
+      doxygen Doxyfile
+
+5. **View the Output**:
+
+   - Open `html/index.html` in a browser.
+
+-----------------
+Best Practices
+-----------------
+
+- **Use meaningful descriptions**: Avoid generic comments.
+- **Keep comments up-to-date**: Maintain consistency with code changes.
+- **Use proper data types**: Always specify accurate types (`int`, `string`, `array`, etc.).
+- **Be concise but informative**: Don’t over-explain obvious things.
+- **Always generate comments above your methods**: Even if the method simply return void.
+
+-----------------
+Conclusion
+-----------------
+
+Using PHPDoc correctly helps create clean, well-documented code. With Doxygen, you can turn comments into structured, browsable documentation.
+
+For more details, refer to:
+- `Doxygen PHP Support <https://www.doxygen.nl/manual/docblocks.html>`_
+- `PHPDoc Standard <https://www.phpdoc.org/>`_

source/fusiondirectory/development/documentation/index.rst

+Writing documentation within your code
+=======================================
+
+How to properly write documentation within your code.
+
+.. toctree::
+   :maxdepth: 2
+
+   PHPDoc
\ No newline at end of file

source/fusiondirectory/development/index.rst

@@ -9,3 +9,4 @@ Development
    codingstyle/index.rst
    writeplugin/index.rst   
    api/index.rst
+   documentation/index.rst