PHPDoc

PHPDoc is a standardized way of writing documentation comments in PHP code. It allows developers to describe the behavior and purpose of classes, methods, functions, constants, and variables within the codebase. Using a specific syntax with annotations (such as @param, @return, etc.), developers can provide detailed information about the code, which can be automatically parsed and converted into human-readable API documentation.

Tools like phpDocumentor can be used to generate this documentation, making it easier for developers to understand, maintain, and collaborate on a codebase.

PHPDoc is slowly losing popularity

With the introduction of better type hinting and attributes, PHPDoc is slowly starting to lose traction. Regardless, you'll find it used heavily in most libraries that have been around. It's still useful to know.

PHPDoc is not an official feature of PHP. It's a standard created by the community. You can find more information about it here: https://docs.phpdoc.org/latest/index.html

Annotations

PHPDoc is made up of annotations. Annotations are like special comments in code that provide additional information about how the code works. They follow a specific format and are often used in documentation.

In PHP, PHPDoc is used to write these annotations, which can then be turned into human-readable documentation.

Here's an example of PHPDoc for a simple function:

/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b) {
  return $a + $b;
}

Breakdown:

Opening Comment: The comment begins with /**. This tells the tools reading the code that what follows is a PHPDoc comment, not just an ordinary comment.
Description: The next lines provide a brief description of what the function does. In this case, "Adds two numbers together."
@param Annotations: The lines beginning with @param describe the parameters or inputs to the function. Here, there are two parameters, $a and $b, and both are described as integers (int).
@return Annotation: The line with @return describes what the function returns. In this case, it returns an integer, described as "The sum of the two numbers."

PHPDoc comments make the code self-documenting. By reading the comments, other developers (or even future you!) can quickly understand what the function is supposed to do, what parameters it needs, and what it returns without having to read the actual code. Tools can also use these comments to generate formal documentation for a project, making it easier for developers to navigate and understand a large codebase.

Other Annotations

PHPDoc offers dozens of annotations, which you can find documented on the official site. Here are some of the most common annotations you'll come across.

Annotation	Description
`@param`	Describes a parameter of a function or method.
`@return`	Describes the return value of a function or method.
`@var`	Describes a variable, typically within a class.
`@throws`	Indicates the exceptions that a function or method can throw.
`@deprecated`	Marks a function, method, or class as deprecated.
`@see`	References other elements, such as functions or URLs.
`@since`	Specifies the version when an element was introduced.
`@todo`	Documents something that needs to be done in the code.

Overall, PHPDoc is a useful way to document your code. It's a concept you'll see in most PHP libraries.

Key Takeaways

PHPDoc is a standardized way of writing documentation comments in PHP, providing detailed information about the code.
Annotations are special comments that follow a specific format, describing aspects such as parameters, return values, variables, and more.
By using PHPDoc, the code becomes self-explanatory, helping developers quickly understand its purpose, parameters, and behavior without diving into the code itself.
A typical PHPDoc comment includes an opening (/**), a general description, and specific annotations (e.g., @param, @return), and may be followed by the code it's documenting.
Many Integrated Development Environments (IDEs) can read PHPDoc comments, providing hints, auto-completion, and other helpful features during coding.

Previous Tutorial:

Understanding Template Engines

Next Tutorial:

Understanding Design Patterns