Keep docblocks only for what types cannot say

How to do it

Use types in the signature where the language has them. Keep a docblock for generic types such as list<Order>, for thrown exceptions, and for units like cents or seconds. Public library functions may keep a one-line summary.

Example

// Bad: says nothing the signature does not
/**
 * @param int $orderId the order id
 * @return Order the order
 */
public function find(int $orderId): Order

// Good: adds what the type system cannot say
/** @return list<Order> newest first, at most 50 */
public function recentFor(CustomerId $customer): array

How to check

A linter flags docblocks that only repeat the parameters. Examples are PHP-CS-Fixer's no_superfluous_phpdoc_tags and ESLint's jsdoc/no-types in TypeScript files.