"Parameter comment must end with a full stop"

[ghost]

phpcs displayed the error "Parameter comment must end with a full stop" on line 717 of the following code:

I don't think this is correct and it's not taking lists into account. Also, I don't see many references to full-stops/periods in the documentation standards, other than the first, summary line of a docblock. So is this actually a thing?

In any case, I don't think adding a full-stop at line 717 solves anything. So something else needs to change here...

[indigoxela]

Seems like you want to rework Backdrop\Sniffs\Commenting?

Sure, give it a stab. (FTR: the rule has been forked from https://github.com/pfrenssen/coder/blob/8.3.x/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php, but we can adapt it to our needs)

[yorkshire-pudding]

There is another comment scenario that it might be worth considering.
In settings.php there are several optional code lines that are commented out. These generate phpcs errors as they don't end with a full stop. Perhaps it would be ok if they ended with ;

[herbdool]

Yes, I agree with adding ; but I think we should also add the backtick for quasi-code such as this example which is from an actual PR:

/**
 *   Examples:
 *    * db:/default/config_active
 *    * db:config_active
 *    * db://config_active
 *    * db:/config_store/config_stage
*/

[herbdool]

This might be what we should be using:

phpcs/Backdrop/Sniffs/Commenting/FunctionCommentSniff.php

Line 995 in a5aa03c

protected function isInCodeExample(File $phpcsFile, $stackPtr, $commentStart)

Wrap the code example in @code/@endcode.

Update: And sure enough, core has lots of examples of that. So we should be using that.

[avpaderno]

I think the issue is that PHP_CodeSniffer expects a comment to always contains sentences, but a comment could also contain a list of items, code, or a phrase. In none of those cases, a period is necessary.
It could be fine to add a period at the end of a phrase, but not for the other cases.

[avpaderno]

This is reported also from the rulesets used for Drupal; I saw many PHP_CodeSniffer reports for contributed modules that included errors about a missing period at the end of a comment.
I guess that either we have a rule that gives false positives, or we disable it.

Can at least the error be changed to a warning?