PHPDoc Guide for Doxygen Usage

This guide explains how to properly document PHP code using PHPDoc comments and generate documentation using Doxygen.

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:

<?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:

/**
 * Short description.
 *
 * Detailed description, spanning multiple lines.
 *
 * @tagname Type Description
 */

Common Tags

Common PHPDoc Tags

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

<?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:

   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:

   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 - PHPDoc Standard