PHPDoc / Docblock

Also Known As

TL;DR

Explanation

PHPDoc docblocks (/** ... */) use tags like @param, @return, @throws, @var, @property, @template, and @deprecated to annotate code. IDEs (PhpStorm, VS Code with Intelephense) use them for autocomplete and type inference; tools like PHPStan and Psalm use them for advanced static analysis; phpDocumentor generates API documentation from them. With modern PHP's native type declarations, many @param and @return tags are redundant — use them to add context, describe array shapes, or document generic types not expressible in PHP's type system.

Common Misconception

Why It Matters

Common Mistakes

• Docblocks that restate the type declarations already visible in the signature — zero added value.
• Missing @throws tags — callers cannot know which exceptions to handle.
• @param with no description for non-obvious parameters — the type is already in the declaration.
• Outdated docblocks that contradict the current code — worse than no docblock.

Code Examples

/**
 * Get user
 * @param int $id The id
 * @return User The user
 */
public function getUser(int $id): User // Docblock adds nothing — all visible in signature

// Valuable docblock:
/**
 * Finds user by ID. Throws if not found because callers must handle absence explicitly.
 * @throws UserNotFoundException if no user with this ID exists
 * @throws DatabaseException on connection failure
 */

/**
 * Transfer funds between two accounts atomically.
 *
 * @param  Account $from      Source account — must have sufficient balance
 * @param  Account $to        Destination account
 * @param  Money   $amount    Amount to transfer — must be positive
 * @return Transfer           The completed transfer record
 * @throws InsufficientFundsException  If $from balance < $amount
 * @throws CurrencyMismatchException   If accounts use different currencies
 */
public function transfer(Account $from, Account $to, Money $amount): Transfer

// Skip docblocks when types + names are already self-documenting:
public function findById(int $id): ?User {} // no docblock needed

References

• ↗ https://docs.phpdoc.org/3.0/guide/references/phpdoc/
• ↗ https://phpstan.org/writing-php-code/phpdoc-types

Tags

Related Terms