Problem/Motivation

Several Twig template docblocks in core use the @see annotation without a space before the referenced class.

@see\Drupal\Core\Form\FormPreprocess::preprocessInput()

According to standard PHPDoc formatting (followed by Drupal coding standards), there should be a space between the annotation and its value.

@see \Drupal\Core\Form\FormPreprocess::preprocessInput()

While this does not affect runtime behavior, without the space @see tags are not correctly parsed by the API module.

Steps to reproduce

Run the following command from the Drupal root:

grep -rni '@see\\Drupal' core/modules

This will return multiple occurrences in Twig template files, for example:

core/modules/system/templates/input.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
core/modules/system/templates/form-element-label.html.twig:12: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElementLabel()
core/modules/system/templates/vertical-tabs.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessVerticalTabs()
core/modules/system/templates/fieldset.html.twig:26: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/modules/system/templates/form.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessForm()
core/modules/system/templates/checkboxes.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessCheckboxes()
core/modules/system/templates/textarea.html.twig:13: * @see\Drupal\Core\Form\FormPreprocess::preprocessTextarea()
core/modules/system/templates/details.html.twig:15: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/modules/system/templates/select.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessSelect()
core/modules/system/templates/form-element.html.twig:44: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/modules/system/templates/radios.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessRadios()
core/modules/field_ui/templates/form-element--new-storage-type.html.twig:16: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/modules/views/tests/themes/views_test_theme/templates/input--submit.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()

grep -rni '@see\\Drupal' core/themes

core/themes/stable9/templates/form/input.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
core/themes/stable9/templates/form/form-element-label.html.twig:12: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElementLabel()
core/themes/stable9/templates/form/fieldset.html.twig:26: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/themes/stable9/templates/form/form.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessForm()
core/themes/stable9/templates/form/checkboxes.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessCheckboxes()
core/themes/stable9/templates/form/textarea.html.twig:13: * @see\Drupal\Core\Form\FormPreprocess::preprocessTextarea()
core/themes/stable9/templates/form/details.html.twig:15: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/stable9/templates/form/select.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessSelect()
core/themes/stable9/templates/form/form-element.html.twig:44: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/themes/stable9/templates/form/radios.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessRadios()
core/themes/stable9/templates/admin/form-element--new-storage-type.html.twig:16: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/themes/stable9/templates/navigation/vertical-tabs.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessVerticalTabs()
core/themes/claro/templates/form/input.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
core/themes/claro/templates/form/checkboxes.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessCheckboxes()
core/themes/claro/templates/form/textarea.html.twig:13: * @see\Drupal\Core\Form\FormPreprocess::preprocessTextarea()
core/themes/claro/templates/form/radios.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessRadios()
core/themes/claro/templates/form-element-label.html.twig:12: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElementLabel()
core/themes/claro/templates/datetime-wrapper.html.twig:6: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/themes/claro/templates/fieldset.html.twig:25: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/themes/claro/templates/navigation/details--vertical-tabs.html.twig:19: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/claro/templates/media-library/fieldset--media-library-widget.html.twig:9: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/themes/claro/templates/media-library/details--media-library-add-form-selected-media.html.twig:8: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/claro/templates/details.html.twig:18: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/claro/templates/form-element.html.twig:6: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/themes/default_admin/templates/form/input.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
core/themes/default_admin/templates/form/form-element-label.html.twig:12: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElementLabel()
core/themes/default_admin/templates/form/textarea.html.twig:13: * @see\Drupal\Core\Form\FormPreprocess::preprocessTextarea()
core/themes/default_admin/templates/form/radios.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessRadios()
core/themes/default_admin/templates/navigation/details--vertical-tabs.html.twig:19: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/default_admin/templates/media-library/fieldset--media-library-widget.html.twig:9: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/themes/default_admin/templates/media-library/details--media-library-add-form-selected-media.html.twig:8: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/starterkit_theme/templates/form/input.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
core/themes/starterkit_theme/templates/form/form-element-label.html.twig:12: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElementLabel()
core/themes/starterkit_theme/templates/form/fieldset.html.twig:26: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/themes/starterkit_theme/templates/form/form.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessForm()
core/themes/starterkit_theme/templates/form/checkboxes.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessCheckboxes()
core/themes/starterkit_theme/templates/form/textarea.html.twig:13: * @see\Drupal\Core\Form\FormPreprocess::preprocessTextarea()
core/themes/starterkit_theme/templates/form/details.html.twig:15: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/starterkit_theme/templates/form/select.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessSelect()
core/themes/starterkit_theme/templates/form/form-element.html.twig:44: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/themes/starterkit_theme/templates/form/radios.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessRadios()
core/themes/starterkit_theme/templates/navigation/vertical-tabs.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessVerticalTabs()
core/themes/olivero/templates/form/fieldset.html.twig:28: * @see\Drupal\Core\Form\FormPreprocess::preprocessFieldset()
core/themes/olivero/templates/form/input--submit--header-search.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
core/themes/olivero/templates/form/details.html.twig:15: * @see\Drupal\Core\Form\FormPreprocess::preprocessDetails()
core/themes/olivero/templates/datetime-wrapper.html.twig:6: * @see\Drupal\Core\Form\FormPreprocess::preprocessFormElement()
core/themes/olivero/templates/form--search-block-form.html.twig:10: * @see\Drupal\Core\Form\FormPreprocess::preprocessForm()

Proposed resolution

Update all occurrences of @see\Drupal to include a space after @see:

- * @see\Drupal\Core\Form\FormPreprocess::preprocessInput()
+ * @see \Drupal\Core\Form\FormPreprocess::preprocessInput()

This aligns the docblocks with PHPDoc standards and Drupal coding conventions.

Remaining tasks

  • Identify all occurrences in core Twig templates
  • Add a space after @see, if there are no spaces after that tag

Issue fork drupal-3578091

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

avpaderno created an issue. See original summary.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Version: 11.x-dev » main
Category: Task » Bug report

avpaderno changed the visibility of the branch 3578091-missing-space-after-@see-tag to hidden.

avpaderno opened merge request !15035

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Status: Active » Needs review
avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented

(I should remember not to use any @ in the branch name.)

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Status: Needs review » Needs work
Issue tags: +Needs issue summary update

I apologize: I found more instances to fix. I will update the issue summary and the MR.

sivaji_ganesh_jojodae’s picture

sivaji_ganesh_jojodae commented
Issue summary: View changes
Issue tags: -Needs issue summary update
sivaji_ganesh_jojodae’s picture

sivaji_ganesh_jojodae commented
Status: Needs work » Needs review

Fixed docblocks by adding a space after @see across Twig templates to comply with coding standards.

Any suggestions on updating phpcs rules to prevent this from getting added in the future?

smustgrave’s picture

smustgrave commented
Status: Needs review » Postponed
Issue tags: +Needs followup

I believe this issue should be postponed until we get a coder rule in place or more will creep in.

I don't even see one attach so we probably need a follow up to get a ticket started over there.

smustgrave’s picture

smustgrave commented
Issue tags: -Needs followup
Related issues: +#3584134: Missing space after the @see tag

Went ahead and add a stub ticket.

smustgrave’s picture

smustgrave commented

Now if a rule exists then it should turned on with the fix here. So we can see all instances are captured.

quietone’s picture

quietone commented
Status: Postponed » Needs review
Issue tags: +Coding standards
Related issues: +#3284817: Adopt vincentlanglet/twig-cs-fixer for Twig coding standards

Changes such as this are better made after core implements linting for twig files so that we don't get regressions. And we do have an issue to add a dependency for linting twig files. That needs an issue summary update so it can be reviewed, #3284817: Adopt vincentlanglet/twig-cs-fixer for Twig coding standards. It would help if someone here would do that so we can start linting twig files. Thanks.

I wouldn't be surprised if these are copy/paste errors and I think the chance of regressions are small. So, I am returning the status to needs review.

dcam’s picture

dcam commented
Status: Needs review » Needs work

There are six additional templates with this problem in the Umami profile's theme.

  • core/profiles/demo_umami/themes/umami/templates/classy/form/textarea.html.twig:13
  • core/profiles/demo_umami/themes/umami/templates/classy/form/radios.html.twig:10
  • core/profiles/demo_umami/themes/umami/templates/classy/form/form-element.html.twig:44
  • core/profiles/demo_umami/themes/umami/templates/classy/form/fieldset.html.twig:25
  • core/profiles/demo_umami/themes/umami/templates/classy/form/details.html.twig:15
  • core/profiles/demo_umami/themes/umami/templates/components/form/form-element-label.html.twig:12
sivaji_ganesh_jojodae’s picture

sivaji_ganesh_jojodae commented

I've updated the MR to include the files in #14.

dcam’s picture

dcam commented
Status: Needs work » Reviewed & tested by the community

Per #13 we're moving this forward despite not having a linting rule for it yet.

There's nothing to say about the MR. It's just adding a bunch of spaces.

I didn't find any other instances of @see annotations that need to be fixed. Personally, I used a slightly different command to check: grep -rni "@see\S" core.

Looks good to me.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Issue summary: View changes

godotislate closed merge request !15035

  • godotislate committed e3a5fd90 on main 
    chore: #3578091 Missing space after the @see tag

By: avpaderno
By:...

  • godotislate committed 12b80f3d on 11.x 
    chore: #3578091 Missing space after the @see tag

By: avpaderno
By:...
godotislate’s picture

godotislate
he/him
commented
Version: main » 11.x-dev
Status: Reviewed & tested by the community » Fixed

Committed and pushed e3a5fd9 to main and 12b80f3 to 11.x. Thanks!

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.