PHPDoc Annotations: When to Use @param and @return

Comments are useful until they merely restate the next line of code. PHPDoc is more valuable when it records a function's contract: what callers must provide, what comes back, and which details are not visible in the native signature. That extra information can help both the next maintainer and static-analysis tools.

What PHPDoc adds to native types

PHP's type declarations can express parameter and return types that the runtime can check. PHPDoc can describe shapes that the signature alone cannot: a list of integers, an array with known keys, or a value that may be null under a particular condition.

/**
 * @param list<int> $postIds Positive post identifiers
 * @return array<int, string> A map of post IDs to titles
 */
function loadTitles(array $postIds): array
{
    // ...
}

The PHP engine does not enforce list<int> just because it appears in a DocBlock. Tools such as PHPStan or Psalm can interpret that extra contract, but only if the implementation actually follows it. An inaccurate annotation does not make the function safer; it gives callers and tools the wrong expectation.

Document the part the signature cannot say

@param and @return are useful when they clarify an ambiguous type or a caller's responsibility. Can an ID list be empty? Is a date expected in UTC? Does failure raise an exception, return null, or return an empty collection? Those details may be worth documenting because they affect how the function is used.

By contrast, repeating function save(User $user): bool word for word in a DocBlock rarely adds anything. Prefer a native declaration when PHP supports the type you need; keep the annotation for richer shapes or important semantics. That keeps documentation close to the code without turning every method into a paragraph.

Keep the contract in sync

When a parameter or return value changes, update the DocBlock in the same change and run the project's analyzer. If the report still describes an old type, the comment has drifted from the implementation. The phpDocumentor syntax reference and its explanation of what a DocBlock is cover the format.

For a broader distinction between ordinary comments and documentation comments, see PHP comment lines and their purpose. Keep a DocBlock when it prevents misuse or tells an analysis tool something the signature cannot; remove it when it only translates the code into prose.