framework icon indicating copy to clipboard operation
framework copied to clipboard

[13.x] chore: remove redundant phpdocs

Open calebdw opened this issue 3 months ago • 12 comments

Hello!

Motivation

The contribution guidelines say to remove redundant tags that provide no additional information over native php types (note that this does not include tags that provide additional information such as descriptions or generics):

image

However, as can be seen by this PR, there are over 6,500 redundant tags in this codebase that are not needed and can be cleaned up. This PR adds the no_superflous_phpdoc_tags rule to the pint config to help enforce the contribution guidelines and clean up the redundant tags.

Removing redundant tags:

  • Enhances Code Readability: Removes redundant PHPDoc tags that duplicate information from PHP's native type hints, reducing visual clutter and making Laravel code easier to read.
  • Aligns with Modern PHP Practices: Encourages concise documentation by eliminating unnecessary @param or @return tags, aligning with Laravel’s emphasis on clean, expressive code.
  • Improves Developer Experience: Streamlines code reviews and maintenance by focusing PHPDoc comments on meaningful insights, such as complex logic or context-specific details.
  • Reduces Maintenance Overhead: Minimizes boilerplate documentation, allowing developers to focus on implementing and maintaining application functionality.

Review

Here's a breakdown of the commits:

  • https://github.com/laravel/framework/pull/56775/commits/ab6eeeec39e53d0f8a2c2f4d15a2e41c8921e8cc This updates the pint config, fixes some stale tags (another reason why this rule is needed), and reworks the event helper so that the phpdocs are not detected as unused and removed
  • https://github.com/laravel/framework/pull/56775/commits/95e65b2f772b60974ba4cc60a4d87cc5d15b8e35 this executes pint on the codebase which removes all the redundant tags

Thanks!

calebdw avatar Aug 26 '25 18:08 calebdw