Our official coding standards for @see requires a fully qualified class and method name.
However, when you're documenting a reference to another method in the same class, this is unfortunate and verbose. See for example #3111463: Improve code documentation for \Drupal\update\ProjectSecurityData.
We already allow @return static and @return $this for documenting return types (see parent issue, #2158497: [policy, no patch] Use "$this" and "static" in documentation for @return types but addressing @see was considered out of scope for that discussion.
Meanwhile, core already has a number of examples of this (recent grep of 8.9.x branch):
./lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php: * @see static::fieldSettingsForm()
./lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php: * @see static::fieldSettingsAjaxProcess()
./lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php: * @see static::fieldSettingsForm()
./lib/Drupal/Core/Field/Plugin/Field/FieldType/EntityReferenceItem.php: * @see static::fieldSettingsForm()
./lib/Drupal/Core/Menu/MenuTreeStorageInterface.php: * @see static::treeDataRecursive()
./lib/Drupal/Core/Url.php: * @see static::fromRoute()
./lib/Drupal/Core/Url.php: * @see static::fromUri()
./modules/book/src/BookManager.php: * @see static::bookTreeGetFlat()
./modules/link/src/Plugin/Field/FieldWidget/LinkWidget.php: * @see static::getUserEnteredStringAsUri()
./modules/link/src/Plugin/Field/FieldWidget/LinkWidget.php: * @see static::getUriAsDisplayableString()
./modules/migrate_drupal/tests/src/Kernel/d6/EntityContentBaseTest.php: // @see static::testOverwriteSelectedNestedProperty()
./modules/simpletest/src/Tests/BrowserTest.php: * @see static::testCookies()
./modules/views/tests/src/Unit/ViewsDataTest.php: * @see static::viewsData()
api.module already gets this right, and generates the correct links in these cases. E.g.:
https://api.drupal.org/api/drupal/core%21lib%21Drupal%21Core%21Menu%21Me...
Update our standards for @see to officially allow using static::methodName() when referring to a method on the same class (and acknowledge a defacto standard that core is already following).
Proposed edits:
- * @see \My\Namespace\MyClass::myMethod()
+ * @see \Full\Namespace\OtherClass::someMethod()
+ * @see static::myMethod()
- method name (with the class)
+ method name (with the class, or static::methodName() if it is a method of the same class)
Alternately, perhaps self::methodName() would be more accurate and better for @see links. See comment #8.
self::methodName() is actually better for @see links than static::methodName() (comment #8)self, static. If both, should one be preferred?N/A
N/A
N/A
N/A
Comments
Comment #2
jhodgdonShouldn't this issue be in the Coding Standards project instead of drupal core?
Comment #3
dwwProbably. I have no idea anymore. I was just copying the attributes of the parent issue. ;) Feel free to re-classify as currently appropriate.
Thanks/sorry,
-Derek
Comment #4
dwwReading https://www.drupal.org/project/coding_standards -- yes, definitely. :)
Moving to the right queue...
Thanks, @jhodgdon!
-Derek
Comment #5
benjifisherNotice that the API docs for MenuTreeStorage::loadTreeData (same link as in the issue summary) include the link static::treeDataRecursive. The link back in the other direction is the long form: \Drupal\Core\Menu\MenuTreeStorage::loadTreeData.
That example is a little unusual, since the
@seecomment is not in the usual position. For a more typical example, see the API docs for EntityReferenceItem::settingsAjax, where "static::fieldSettingsForm()" is in the usual "See also" section.I am in favor of this proposal.
Comment #6
alexpott+1 to this proposal.
Comment #7
quietone commented+ 1
Comment #8
dwwNot to muddy the waters, but I wonder if for the purposes of @see links (what this issue is about), if
self::methodName()would actually be better.static::methodName()is "nice" for late bindings and all that, but documentation links are supposed to be deterministic. ;) They have to link somewhere, and the intention here is to link to another method in the same class, which is ultimately whatself::is about. Also, for folks not fully steeped in the arcane inner workings of PHP's OO universe,self::fooBar()is perhaps more self-documenting and understandable, whereasstatic::fooBar()might add confusion. I imagine if I didn't know anything about any of this mess, and I saw "@see self::fooBar()", I'd be able to guess that means "Look at the fooBar() in myself", which is exactly what we mean.Sorry I didn't propose this originally. Some folks have already +1'ed this issue when it was just about
static::. Now they'll have to reconsider forself::. Apologies!Thoughts?
Thanks!
-Derek
Comment #9
alexpott+1 to either self or static - api.drupal.org and PHPStorm both do the correct thing in either case. I don't think there's much gained by prescribing one over the other.
Comment #10
benjifisherBoth are already used in core, and
selfis more common:One example is FormState::$complete_form, which has reference to
self::getCompleteForm(). Looking at that page confirms that api.drupal.org creates the link correctly.I am updating the title and the remaining tasks in the IS, but not the proposed resolution.
Is there a difference on a.d.o between
@see selfand@see staticwhen a method is overridden and we use{@inheritdoc}in the doc block?For example,
ContentEntityTypeInterface::getRevisionMetadataKey()has@see self::getRevisionMetadataKeys(). Looking at the API docs for the implementation, ContentEntityType::getRevisionMetadataKey I see a link to the implementation, which seems a little inconsistent. The API page for the interface has a link to the interface method.The only example of
@see staticin a core interface is MenuTreeStorageInterface::loadTreeData, which has@see static::treeDataRecursive()inside the@returncomment. The reference does not generate a link in the API doc page for the interface, but it does generate a link (to the implementation) on the page for the implementation.So I do not like the inconsistency of
@see self, but I think the failure to generate a link on the interface's API page is a bigger problem for@see static. Unfortunately, I do not see a way test what happens with a normal@see staticcomment in an interface: does the "See also" section get generated or not?Maybe we need a child issue where we move the
@seecomment out of the@returncomment as a test.Comment #11
drunken monkeyPlease also see #2341405: Decide on standard for referencing namespaced classes, where we’ve been discussing a slightly broader proposal for over five years now. ;)
The current proposal there is to omit everything before the double colon (
::) altogether, but usingself::*would also make sense, of course. (I agree thatstatic::*would be a little weird in this context.)Also, I don’t quite see a reason to limit this to
@seecomments. Anyways, I’d much prefer resolving this for as many unnecessary namespaces at once, but would also be quite happy to have it just for this single case. Feel free to adapt my text from the other issue for your actual proposed wording in the standards.Comment #12
dww@drunken monkey: Thanks for the link! Agreed these are closely related. Perhaps this one should be duplicate. I just found this particular case to not make sense, searched for issues mentioning '@see', didn't find anything, and opened this one. I've been burned so many times with "out of scope" that I now tend to craft all issues with very narrow scope. Happy to merge these if the folks that make these decisions prefer, or happy to leave them separate if this small aspect is easier to deal with on its own (and hopefully in turn makes it easier to fix #2341405: Decide on standard for referencing namespaced classes).
Comment #13
dwwShould we merge this into #2341405: Decide on standard for referencing namespaced classes, or leave this as a smaller scoped (and therefore hopefully easier) issue to resolve?
Thanks,
-Derek
Comment #14
joachim commentedI'd say we could resolve this as it stands?
It's been dormant for 2 years, would be good to get it done.