Follow-up to #2707371: Fix several errors in the 'Drupal.Commenting.DocComment' coding standard

Problem/Motivation

Let's fix drupal/coder's sniffs in core.

This issue continues fixing Drupal.Commenting.DocComment errors. These errors relate to docblock comments and the tags within them.

We'll limit to easy-to-review errors: ShortStartSpace, SpacingAfter

ShortStartSpace makes sure the one-line summary is indented properly.

SpacingAfter makes sure there are no blank lines at the end of docblocks.

Proposed resolution

Add drupal/coder and the phpcs package to your Drupal codebase:

# From Drupal root directory
$ composer require drupal/coder
$ ./vendor/bin/phpcs --config-set installed_paths DRUPALPATH/vendor/drupal/coder/coder_sniffer/

Modify the Drupal.Commenting.DocComment errors to not be excluded from within core/phpcs.xml.dist.

Run phpcbf from the core directory:

$ cd core
$ ../vendor/bin/phpcbf

This will fix some errors. Review what it did and fix problematic changes.

Run phpcs from the core directory in order to verify that no errors remain:

$ ../vendor/bin/phpcs -p

To review this issue

Install coder/phpcs as above.

Apply the patch.

Run phpcs from the core directory to verify that no errors remain.

$ cd core
$ ../vendor/bin/phpcs -p

Read the patch to check for errors.

Remaining tasks

User interface changes

API changes

Data model changes

CommentFileSizeAuthor
#3 2716685_3.patch43.4 KBMile23
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Mile23 created an issue. See original summary.

Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 as a volunteer commented
Issue summary: View changes
Related issues: -#2715741: Fix 'Drupal.Classes.FullyQualifiedNamespace' coding standard +#2707371: Fix several errors in the 'Drupal.Commenting.DocComment' coding standard
Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 as a volunteer commented
Issue summary: View changes
Related issues: +#2060925: False-positives for @code/@endcode by Drupal.Commenting.DocCommentSniff and Drupal.Commenting.DocCommentAlignment sniff
FileSize
2716685_3.patch43.4 KB

WebTestBase.php still suffers from #2060925: False-positives for @code/@endcode by Drupal.Commenting.DocCommentSniff and Drupal.Commenting.DocCommentAlignment sniff in a rather complex way, so ParamGroup error will stay in the exclude list and I won't fix WebTestBase (since it isn't broken).

However I'll leave all the other changes related to ParamGroup in this patch since they're easy to read.

ParamGroup just wants all @param tags to be together, with no blank lines between them.

Since ShortStartSpace adjusts the first line of docblocks, auto-fixing it results in some strange spacing for some docblocks with no first line summary. In those cases, I properly indented the whole paragraph.

Fixing the remaining Drupal.Commenting.DocComment errors will require subjective review, as well as fixing the issues with false positives.

Mile23’s picture

Mile23
Primary language English
Location Seattle, WA
CreditAttribution: Mile23 as a volunteer commented
Status: Active » Needs review
alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott at Chapter Three commented
Status: Needs review » Reviewed & tested by the community

The changes here look good and phpcs reports no errors after applying the patch.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
CreditAttribution: alexpott at Chapter Three commented
Status: Reviewed & tested by the community » Fixed

Committed 1d7b860 and pushed to 8.1.x and 8.2.x. Thanks!

  • alexpott committed 70f5886 on 8.2.x 
    Issue #2716685 by Mile23: Part 2: Fix several errors in the 'Drupal....

Status: Fixed » Closed (fixed)

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