We are using a tool named doxygen which is fantastic to read documented code and offers a visual
##############################
reprensentation of the interaction of classes and methods.
PHPDoc Guide for Doxygen Usage
##############################
If well documented, the visuals helps to quicker understand the codes.
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;
}
}
How to document your code
-------------------------
-------------------------
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
**Within your methods**
5. **View the Output**:
- Open `html/index.html` in a browser.
You may comment your code inline above your line of code in order to make a clear message on what/why/how
