The 2026 Drupal Business Survey is open. Your response will help shape the future of the Drupal business ecosystem.In many places in core we have comments like:
/**
* (optional) The short title used in the views UI.
*
* @var \Drupal\Core\Annotation\Translation
*
* @ingroup plugin_translatable
*/
public $short_title = '';
Drupal.Commenting.DocComment.ShortNotCapital doesn't allow the comment to start with "(optional)".
| Comment | File | Size | Author |
|---|---|---|---|
| #6 | 2925237-6.patch | 7.22 KB | BartoszUrbaniak |
Comments
Comment #2
idebr commentedThis is part of #2909370: Fix 'Drupal.Commenting.VariableComment.IncorrectVarType' coding standard
Comment #3
alexpottI don't think that having any optional standard for @var doesn't really make any sense. It's not a param being passed in. I don't think it adds anything to the documentation. In fact for me it makes think "huh? I wonder what they mean by optional".
Imo this is won't fix works as designed.
Comment #4
idebr commentedThere is documentation available on the 'Coding standards' pages on how to type hint optional parameters:
https://www.drupal.org/docs/develop/coding-standards/api-documentation-a...
Comment #5
alexpott@idebr a class property is not a parameter. These are different things.
Comment #6
BartoszUrbaniak commentedI have created the patch for this issue, which removes comments in class properties started with "(optional)".
Comment #7
mfernea commented@BartoszUrbaniak I think the patch uploaded relates to Drupal core while this issue is made for Coder.
Comment #8
liam morlandThe problem is that Drupal.Commenting.DocComment.ShortNotCapital is triggered by characters that cannot be capitalized. For example, the comment
'0' won't work as a key for checkboxestriggers it. This should only be triggered for things that are lower-case, not characters that do not have case.Related issue:
https://github.com/squizlabs/PHP_CodeSniffer/issues/2490
Comment #9
klausiI agree with @alexpott, the "(optional)" does not make sense as start of a doc comment for a function or class property.
@Liam: "'0' won't work as a key for checkboxes" also does not sound like a proper doc comment for a function or class property. Can you give more context where you got that example from?
Comment #10
liam morlandIt's a comment in the Webform module.
The main point is that this error should not be triggered for characters that do not have case. If it is required that comments start with a letter that is separate from a requirement that letters be capital.