PHPDoc in PHP

Write professional documentation comments in PHP using PHPDoc — document functions, classes, properties, parameters, return types, and exceptions.

PHPDoc Basics

PHPDoc is a documentation standard for PHP code. A PHPDoc block starts with `/**` (double asterisk) and sits directly above the thing it documents — a function, class, method, or property. IDEs (PhpStorm, VS Code), static analysers (PHPStan, Psalm), and documentation generators (phpDocumentor) all parse PHPDoc blocks.

1. PHPDoc Block Structure

Summary, description, and tag sections.

2. PHPDoc vs Native Type Hints

When PHPDoc adds value beyond native PHP type hints.

Essential PHPDoc Tags

PHPDoc has a standard set of tags. Knowing the most common ones covers 95% of real-world documentation needs.

1. @param, @return, @throws

Document function inputs, outputs, and exceptions.

2. @var, @property, @method

Document class properties, magic properties, and magic methods.

3. @template — Generic-Style Type Hints

Document generic functions and classes with @template.

4. Other Useful Tags

@deprecated, @see, @link, @author, @since, @example.

Documenting Classes & Interfaces

A well-documented class tells the reader what it represents, what it can do, and how to use it — without reading the implementation.

1. Documenting a Class

Class-level docblock, constructor, properties, and methods.

2. Documenting an Interface

Document interface contracts so implementors know exactly what is expected.

PHPDoc Tooling

PHPDoc is most powerful when paired with tools that read it. PHPStan and Psalm catch type errors before runtime. phpDocumentor generates HTML reference documentation automatically.

1. Static Analysis with PHPStan & Psalm

Use PHPDoc to catch type errors statically before they reach production.

2. Generating Documentation with phpDocumentor

Auto-generate HTML reference docs from PHPDoc blocks.

3. PHPDoc Best Practices

What to document, what to skip, and how to write clear comments.