Drupal coding standard for function parameters (@param), function return values (@return), and thrown exceptions (@throws) comments is a new line which is indented two spaces. If an indent is less than 2 spaces, phpcs marks this as sniff violation, but in case there are more than 2 spaces - it is considered ok. I was looking at some code which was looking funny because of too many spaces.

 * @param string $mail
 *          The email address.
 * @param string $name
 *          The full name of user.

This should be an easy fix. I will rollout a patch in few minutes.

CommentFileSizeAuthor
#5 function-comment-indent-2634008-5.patch2.02 KBshahinam
#3 function-comment-indent-10663530-3.patch2.02 KBshahinam

Comments

shahinam created an issue. See original summary.

shahinam’s picture

shahinam commented
Issue summary: View changes
shahinam’s picture

shahinam commented
StatusFileSize
new function-comment-indent-10663530-3.patch2.02 KB

Here goes the patch.

This sniff violation is marked as automatically fixable by phpcbf, and it seems to do it correctly.

shahinam’s picture

shahinam commented
Status: Active » Needs review
shahinam’s picture

shahinam commented
StatusFileSize
new function-comment-indent-2634008-5.patch2.02 KB

Oops, file name was wrong, Fixed!

  • klausi committed c684c2c on 8.x-2.x 
    Issue #2634008: Added a test case to demonstrate indented lists in @...
klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Needs review » Needs work

Unfortunately not that easy. I committed a test case that demonstrates a valid use of @param comments with nested lists that are indented farther than 3 spaces.

We should only check if the indentation is more than 3 on the first line of the @param comment. We should ignore more indentation on the following lines, but still validate that it is never less than 3.

anoopjohn’s picture

anoopjohn commented

How should this be handled correctly? Is there code in coder parser that correctly parses and identifies lists and depths? Checking for depths and corresponding indentation in lists is tricky. I was trying to come up with the test case for this first. Here is what I have.

/**
 * Param comment indentation should be three spaces.
 *
 * Lists will have to be handled separately though.
 *
 * @param string $arg1
 *      This is not indented correctly.
 * @param string $arg2
 * This is not indented correctly.
 * @param string $arg3
 *   This is indented correctly.
 *   - This is indented correctly. This is a long line in the list which is
 *     wrapped and indented correctly.
 *     This is also indented correctly and will be part of above item
 *    - This is indented incorrectly.
 *   - This is valid:
 *     - So is this:
 *       - So is this:
 *         - So is this.
 *           So is this line.
 *       So is this line.
 *     - So is this.
 *         However this is not indented correctly.
 *     But this is indented correctly.
 *   So is this.
 */
function test20($arg1, $arg2, $arg3) {
}

Is it required by the API documentation parser to have lists preceded by ':' or is it just that you need to have a '-' at the start of the line?

I hope the above case has handled all the scenarios. I can think of only two conditions that can be used to validate the spacing

a) Spacing should be 3+2(n-1) where n is the depth of the list for start lines of list items and 3+2n for overflow lines of list items
b) Once inside a list a new comment line will have to be at the indentation of the current list item or at any of the indentation levels from 3 to 3+2n

I am not sure if auto correct will work when inside lists and whether we will be able to logically detect if indentation is correct once inside list contexts other than basic tests with the above conditions. For cases when there are no lists around we can autofix for the 3 space rule.