Updated: Comment #2

Problem/Motivation

The sniffer review was updated to allow {@inheritdoc} in docblocks. However, it is still flagged as an error by the release standards review. It is unacceptable for the Coder module to report errors for code that complies with Drupal coding standards.

Proposed resolution

I have added {@inheritdoc} to the regex for strings that will not be considered code in comments. This fixes the immediate problem. Additional checks are needed to fully check compliance with API documentation and comment standards.

Remaining tasks

  1. Add a release standards rule to report an error if {@inheritdoc} appears in an inline comment rather than a docblock comment.
  2. Add a release standards rule to report an error if the comment in which {@inheritdoc} appears is not a class member description.
  3. Add a release standards rule to report an error if {@inheritdoc} is not the only line in the docblock.
  4. Fix FunctionCommentSniff.php to report an error if {@inheritdoc} is not the only line in the docblock.
  5. Move the function comment that contains {@inheritdoc} along with additional lines from good.php to bad.php.
CommentFileSizeAuthor
#1 coder-inheritdoc-2163269.patch959 bytesdarren oh

Comments

darren oh’s picture

darren oh
Primary language English
Location Lakeland, Florida
commented
Assigned: darren oh » Unassigned
Issue summary: View changes
Status: Active » Needs review
StatusFileSize
new coder-inheritdoc-2163269.patch959 bytes
darren oh’s picture

darren oh
Primary language English
Location Lakeland, Florida
commented
Issue summary: View changes

Fixed typos in remaining tasks list.

darren oh’s picture

darren oh
Primary language English
Location Lakeland, Florida
commented
Issue summary: View changes

Clarified that we need additional rules to be added to the release standards review, not additional reviews.

jonathan1055’s picture

jonathan1055 commented
Related issues: +#1906474: [policy adopted] Stop documenting methods with "Overrides …"

Thanks Darren Oh. This works for me. Scheduler has several {@inheritdoc} and your patch cleans up the incorrect warnings.

For reference I have added as a related issue the original thread in which the policy was discussed and adopted.

darren oh’s picture

darren oh
Primary language English
Location Lakeland, Florida
commented
Status: Needs review » Reviewed & tested by the community
darren oh’s picture

darren oh
Primary language English
Location Lakeland, Florida
commented
Issue summary: View changes
jonathan1055’s picture

jonathan1055 commented

Any chance this can get committed, please? Darren did a good job, this has helped our project, and it's been RTBC for 3 months.

  • klausi committed 3f120c4 on 7.x-2.x authored by Darren Oh 
    Issue #2163269 by Darren Oh: Coder Review - Allow {@inheritdoc} same as...
klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Reviewed & tested by the community » Fixed

Committed, thanks!

Coder Review is a bit lagging behind and has been removed from 8.x-2.x. Coder Sniffer is recommended to check your code. But since it also seems this does not hurt either I went ahead and committed it.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.

jonathan1055’s picture

jonathan1055 commented

Thanks for committing this, it is a great help.
In a similar fashion, could you also consider #1834598: Coder_Review does not recognize @file docblock in .js files and #1984908: "Docblock should be immediately above" - Carriage Return Line Feed problems as these have good patches which really help to remove bogus warning.
Thank you for a great module - very useful indeed.
Jonathan