Come together with the global Drupal community in Rotterdam, 28 Sept – 1 Oct 2026. Sessions, contribution, connection, and Early Bird savings until 8 June.Problem/Motivation
I am finding LOTS of namespaces in API documentation that are not fully-qualified (starting with \).
They need to be.
I don't even know where to start in fixing this but I'm filing this issue... It's a problem for the API module as well as IDEs if namespaces do not start with \ -- we discussed this a while back and although not everything with namespaces in documentation was agreed upon, this one point was agreed upon by everyone. Our standard is that they *must* start with \ and many of them in core don't.
If you use a namespace on a class anywhere in documentation, always make sure it is a fully-qualified namespace (beginning with a backslash).
From the Drupal Coding Standards
Steps to reproduce
Proposed resolution
Fix the references to classes and interfaces that are not using a FQN in comments.
Remaining tasks
Explore having a sniff to find the occurrences.
User interface changes
Introduced terminology
API changes
Data model changes
Release notes snippet
| Comment | File | Size | Author |
|---|---|---|---|
| #5 | 2030977-qualified-drupal-class-5a.patch | 608.79 KB | pancho |
| #5 | 2030977-qualified-drupal-class-5b.patch | 595.58 KB | pancho |
Comments
Comment #1
chx commentedOver all files:
file_put_contents($filename, preg_replace('/(?<=\\)Drupal\\', '\\Drupal\\', file_get_contents($filename));. The number of backslashes is not tested, might need four.Comment #2
jhodgdonTagging so I can have some hope of finding this issue when it slides into obscurity
Comment #3
chx commentedComment #4
jhodgdonThat regexp would need to be adjusted to only find Drupal\ without a \ preceding *in comments* because we definitely don't want to "fix" this in use/namespace statements in code!
Comment #5
panchoHuge patches resulting from this code:
Seem to work fine, so no unintended code instances should have been changed.
Had to split them because it otherwise broke the uploader.
Comment #6
panchoComment #8
panchoNot yet quite there. We're still catching some functional code. Regex needs to ensure we're in a comment.
Comment #9
jhodgdonI would suggest that to detect we're in a comment, look for lines whose first non-whitespace characters are either "*" or "//".
That may not be "correct" in the sense of "would match in anything I could dream up", but I think it would most likely be "correct" in the sense of "for practical purposes in Drupal 8.x code, this would match what I want it to match and avoid matching non-comment uses of namespaces".
Comment #10
tim.plunkettThis is a DX problem for IDE users, and might make API.module grouchy, but it is in no way a major bug.
Comment #11
xano@pancho, what's the difference between your A and B patches?
Comment #25
smustgrave commentedThank you for creating this issue to improve Drupal.
We are working to decide if this task is still relevant to a currently supported version of Drupal. There hasn't been any discussion here for over 8 years which suggests that this has either been implemented or is no longer relevant. Your thoughts on this will allow a decision to be made.
Since we need more information to move forward with this issue, the status is now Postponed (maintainer needs more info). If we don't receive additional information to help with the issue, it may be closed after three months.
Thanks!
Comment #26
smustgrave commentedSince there's been no follow up going to close out. But don't worry this can always be re-opened if needed for D11.
Thanks all
Comment #27
quietone commentedRestoring status. This is still relevant.
Comment #28
quietone commented