[Meta] Fix 'Drupal.Commenting.FunctionComment' coding standard [#2572645]

Part of #2571965: [meta] Fix PHP coding standards in core.

Approach

We are testing coding standards with PHP CodeSniffer, using the Drupal coding standards from the Coder module. We need to do a couple of steps in order to download and configure them so we can run a coding standards check.

Step 1: Add the coding standard to the whitelist

Every coding standard is identified by a "sniff". For example, an imaginary coding standard that would require all llamas to be placed inside a square bracket fence would be called the "Drupal.AnimalControlStructure.BracketedFence sniff". There are dozens of such coding standards, and to make the work easier we have started by only whitelisting the sniffs that pass. For the moment all coding standards that are not yet fixed are simply skipped during the test.

Open the file core/phpcs.xml.dist and add a line for the sniff of this ticket. The sniff name is in the issue title. Make sure your patch will include the addition of this line.

Step 2: Install PHP CodeSniffer and the ruleset from the Coder module

$ composer install
$ ./vendor/bin/phpcs --config-set installed_paths ../../drupal/coder/coder_sniffer

Once you have installed the phpcs package, you can list all the sniffs available to you like this:

$ ./vendor/bin/phpcs --standard=Drupal -e

This will give you a big list of sniffs, and the Drupal-based ones should be present.

Step 3: Prepare the phpcs.xml file

To speed up the testing you should make a copy of the file phpcs.xml.dist (in the core/ folder) and save it as phpcs.xml. This is the configuration file for PHP CodeSniffer.

We only want this phpcs.xml file to specify the sniff we're interested in. So we need to remove all the rule items, and add only our own sniff's rule. Rule items look like this:

<rule ref="Drupal.Classes.UnusedUseStatement"/>

Remove all of them, and add only the sniff from this issue title. This will make sure that our tests run quickly, and are not going to contain any output from unrelated sniffs.

Step 4: Run the test

Now you are ready to run the test! From within the core/ folder, run the following command to launch the test:

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

This takes a couple of minutes. The -p flag shows the progress, so you have a bunch of nice dots to look at while it is running. The -s flag shows the sniffs when displaying results.

Step 5: Fix the failures

When the test is complete it will present you a list of all the files that contain violations of your sniff, and the line numbers where the violations occur. You could fix all of these manually, but thankfully phpcbf can fix many of them. You can call phpcbf like this:

$ ../vendor/bin/phpcbf

This will fix the errors in place. You can then make a diff of the changes using git. You can also re-run the test with phpcs and determine if that fixed all of them.

List of sub-sniffs related to Drupal.Commenting.FunctionComment

The following is the list of sub-sniffs related to Drupal.Commenting.FunctionComment. The number prefix is the number of failures/number of files for the sub-sniff in a run of coder on 10.0.x branch.

The grouping is a proposed way of handling all the issues. Please remember to update specific issue numbers in the list below if any other sub-sniffs are taken up to avoid duplication of efforts.

Missing

941/387 - Drupal.Commenting.FunctionComment.Missing - I think we may have to reduce the severity level for this / exclude this for a while as it would take quite a bit of effort to understand the respective functions and write meaningful and useful comments. - #3212066: Fix Drupal.Commenting.FunctionComment.Missing
675/388 - Drupal.Commenting.FunctionComment.MissingReturnComment
762/236 - Drupal.Commenting.FunctionComment.MissingParamType - #3207949: Fix Drupal.Commenting.FunctionComment.MissingParamType

Issues with @see

Drupal.Commenting.FunctionComment.SeeAdditionalText
Drupal.Commenting.FunctionComment.SeePunctuation

Spacing / Styling issues

Drupal.Commenting.FunctionComment.SpacingAfterParamType
Drupal.Commenting.FunctionComment.SpacingAfter
Drupal.Commenting.FunctionComment.WrongStyle

Issues with @throws

Drupal.Commenting.FunctionComment.ThrowsComment
Drupal.Commenting.FunctionComment.ThrowsNoFullStop
Drupal.Commenting.FunctionComment.ThrowsNotCapital

Comment	File	Size	Author
#10	Drupal.Commenting.FunctionComment-2572645-10.patch	719.63 KB	vprocessor
#10	8.2.x: PHP 5.5 & MySQL 5.5 18,485 pass
#10	Drupal.Commenting.FunctionComment-2572645-10.interdiff.txt	490 bytes	vprocessor
#9	Drupal.Commenting.FunctionComment-2572645-9.patch	719.15 KB	vprocessor
#9	8.2.x: PHP 5.5 & MySQL 5.5 18,485 pass
#2	Drupal.Commenting.FunctionComment.patch	22.56 KB	attiks
#2	8.0.x: PHP 5.5 & MySQL 5.5 13,907 pass

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

22 September 2015 at 13:17

attiks created an issue. See original summary.

Comment #2

attiks CreditAttribution: attiks commented 22 September 2015 at 13:19

File	Size
Drupal.Commenting.FunctionComment.patch	22.56 KB
8.0.x: PHP 5.5 & MySQL 5.5 13,907 pass

Comment #3

DuaelFr

he/him

French

Montpellier, France

CreditAttribution: DuaelFr as a volunteer and at Happyculture commented 24 September 2015 at 13:00

Issue tags:

-Novice

As agreed between the mentors at Drupalcon, according to issues to avoid for novices, I am untagging this issue as "Beginner". This issue contains changes across a very wide range of files and might create too many other patches to need to be rerolled at this particular time. This patch has an automated way to be rerolled later so better to implement it after Drupalcon.

Comment #4

tatarbj

Hungarian

Brussels

CreditAttribution: tatarbj commented 24 September 2015 at 14:18

Status:

Needs review

» Needs work

Unfortunately it needs more manual work to be ready to commit it, there are a lot of empty @file docs what need to fill up with valid header documentations.

Comment #5

pfrenssen

Sofia

CreditAttribution: pfrenssen commented 27 November 2015 at 11:42

Issue summary:

Title:	Fix 'Drupal.Commenting.FunctionComment' coding standard	» [plan] Fix 'Drupal.Commenting.FunctionComment' coding standard
Category:	Task	» Plan

Issue summary:	View changes
Issue tags:	-Needs issue summary update

[Meta] Fix 'Drupal.Commenting.FunctionComment' coding standard