I've run across an issue in drupal 8.x form.inc where we have @code...@endcode within the last @param for a function doc, here's the current code:
* @param ...
* Any additional arguments are passed on to the functions called by
* drupal_form_submit(), including the unique form constructor function.
* For example, the node_edit form requires that a node object be passed
* in here when it is called. Arguments that need to be passed by reference
* should not be included here, but rather placed directly in the $form_state
* build info array so that the reference can be preserved. For example, a
* form builder function with the following signature:
* @code
* function mymodule_form($form, &$form_state, &$object) {
* }
* @endcode
* would be called via drupal_form_submit() as follows:
* @code
* $form_state['values'] = $my_form_values;
* $form_state['build_info']['args'] = array(&$object);
* drupal_form_submit('mymodule_form', $form_state);
* @endcode
Here are the errors i get for the code above:
697 | ERROR | Last parameter comment requires a blank newline after it
705 | ERROR | Expected 1 space between asterisk and tag; 3 found
708 | ERROR | Expected 1 space between asterisk and tag; 3 found
710 | ERROR | Expected 1 space between asterisk and tag; 3 found
714 | ERROR | Expected 1 space between asterisk and tag; 3 found
It seems that when the last @param ends with a @code block the sniff for the newline after the @param block isn't working correctly (in this case there isn't a line space after the last @param, but even when you put on in after the @endcode you still get the same error reported). The sniff seems to expect the newline after "...function with the following signature:" instead of after the @endcode.
And how are we meant to format the @code and @endcode? Indented 3 spaces to match the other content of the @param block as shown above, or indented 1 space to the same level as @param:
* @param ...
* Any additional arguments are passed on to the functions called by
* drupal_form_submit(), including the unique form constructor function.
* For example, the node_edit form requires that a node object be passed
* in here when it is called. Arguments that need to be passed by reference
* should not be included here, but rather placed directly in the $form_state
* build info array so that the reference can be preserved. For example, a
* form builder function with the following signature:
* @code
* function mymodule_form($form, &$form_state, &$object) {
* }
* @endcode
* would be called via drupal_form_submit() as follows:
* @code
* $form_state['values'] = $my_form_values;
* $form_state['build_info']['args'] = array(&$object);
* drupal_form_submit('mymodule_form', $form_state);
* @endcode
The above code fixes the "Expected 1 space between asterisk and tag; 3 found" errors
I checked the api definition and the code blocks are displayed correctly within the @param definition: https://api.drupal.org/api/drupal/core%21includes%21form.inc/function/drupal_form_submit/8
(As a side note, there is a code block missing at the end of that definition tho, after for example:)
* For example:
* @code
* // register a new user
* $form_state = array();
* $form_state['values']['name'] = 'robo-user';
* $form_state['values']['mail'] = 'robouser@example.com';
* $form_state['values']['pass']['pass1'] = 'password';
* $form_state['values']['pass']['pass2'] = 'password';
* $form_state['values']['op'] = t('Create new account');
* drupal_form_submit('user_register_form', $form_state);
* @endcode
Comments
Comment #1
Mile23@code and @endcode blocks are showing some false-positives here: #2707371: Fix several errors in the 'Drupal.Commenting.DocComment' coding standard
The sniffer thinks they are further tags like @param, so it says things like this:
Here's a link to line 42 of FormattableMarkup, the first error above: http://cgit.drupalcode.org/drupal/tree/core/lib/Drupal/Component/Render/...
Note that it gives this error on the second use of @code, because it thinks @endcode is another type of tag, rather than a presentation markup.
Comment #2
cferthorneyCould we just do a switch statement along the lines of:
It generates a "There must be exactly one blank line before the tags in a doc comment" error but I want to check I'm on the right lines with this before I submit a patch, and try to write tests, etc.
Comment #3
TR CreditAttribution: TR commentedSame problem as reported in #1, this is still an issue.
The first @code/@endcode does not generate coding standards errors.
However, each @code or @endcode after that will result in the error:
So the above doc block will generate FOUR codings standards errors, when it should generate zero.
Comment #4
RoSk0Cross-linking #2937858: Fix 'Drupal.Commenting.DocCommentAlignment' coding standard.
Comment #5
RoSk0Added sniff name to title
Comment #6
TR CreditAttribution: TR commented#1 and #3 errors are generated by Drupal.Commenting.DocCommentSniff, not by Drupal.Commenting.DocCommentAlignment.
Maybe this should be split into two issues, but let's not ignore #1 and #3 by changing the title and narrowing the issue.
Comment #7
jhodgdonI would also like to note that the suggested fix in the issue summary
is incorrect from the perspective of working on api.drupal.org. That would result in that @code/@endcode block being considered *not* to be part of the @param documentation, because the API module uses indentation changes (to the left, as in this case) to indicate "that's the end of the preceding doc block section".
So, if there's a sniff that doesn't allow @code/@endcode and apparently @link (see #2937858: Fix 'Drupal.Commenting.DocCommentAlignment' coding standard) to be indented the same as the surrounding text, then that sniff is incorrect.
Comment #8
btully CreditAttribution: btully as a volunteer and commentedAny update on this? Currently there doesn't seem to be a way to reliably run phpcs on a D8 codebase with all of these sniff errors resulting from the usage of @code/@endcode in comments, which is how 99% of all core/contrib code seems to do things.
I've followed the suggestion from @cferthorney above and modified vendor/drupal/coder/coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php and at https://git.drupalcode.org/project/coder/blob/8.x-3.x/coder_sniffer/Drup... I added the following:
And the frequent "Tags must be grouped together in a doc comment" disappeared.
Should we roll a patch?
Comment #9
TR CreditAttribution: TR commented@btully: That was proposed by @cferthorney in #2, but in that comment he said:
So are you saying that doesn't occur for you?
The best thing to do it roll a patch because that will show exactly what you propose to do and will allow others to try it and see if there are any side effects ... but first I suggest you test any patch first to ensure it addresses all the problems listed above ...
Comment #10
klausiWork in progress at https://github.com/pfrenssen/coder/pull/49
Lot's of annoying exceptions we have to make for @code tags, I have not looked into @return code tags yet.
Comment #12
klausiAdded test for return tags and all your examples in this issue as test cases.
This should fix quite a lot of cases, please open new issues when you find more special cases.
Comment #13
klausi