Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
API page: https://api.drupal.org/api/drupal/includes%21common.inc/function/entity_...
This is missing a @return. Adding this with the interface DrupalEntityControllerInterface specified would allow the docs for this function to have a link to the interface, which itself has a link to https://api.drupal.org/api/drupal/includes!entity.inc/class/DrupalDefaul.... This would make it easier to navigate on api.d.org.
Comment | File | Size | Author |
---|---|---|---|
#14 | interdiff-7-14.txt | 351 bytes | cs_shadow |
#14 | drupal-missing_@return-2245057-14.patch | 553 bytes | cs_shadow |
#7 | interdiff-3-7.txt | 467 bytes | cs_shadow |
#7 | drupal-missing_@return-2245057-7.patch | 552 bytes | cs_shadow |
#3 | interdiff-1-3.txt | 540 bytes | cs_shadow |
Comments
Comment #1
cs_shadow CreditAttribution: cs_shadow commentedAttached is a patch that adds the '@return '. Any suggestions regarding the text in the doc block are welcome.
Comment #2
joachim CreditAttribution: joachim commentedThanks!
You should put the interface on the @return itself, eg:
The return text can just be something like "The entity controller object for the entity type."
While we're at it, this is slightly wrong:
> Get the entity controller class for an entity type.
We're not getting a class name, we're getting the actual controller.
Comment #3
cs_shadow CreditAttribution: cs_shadow commentedAttaching the new patch and the interdiff. Changed the return text and function description.
@joachim, Thanks. With your help, I learned some new things on how to write documentation.
Comment #4
joachim CreditAttribution: joachim commentedPerfect. Thanks!
Comment #5
jhodgdonAfter any @tag, our policy is that you need to include the namespace with a class name. Thanks!
Comment #6
jhodgdonAlso the docs are indented 3 spaces on the line after the @return and it should only be 2.
Comment #7
cs_shadow CreditAttribution: cs_shadow commentedFixed the indentation issue. Not sure what you meant in #5 because I've already included the name of the interface.
@jhodgdon, please tell me if I'm missing something.
Comment #8
cs_shadow CreditAttribution: cs_shadow commentedComment #9
jhodgdonThe @return needs the PHP *Namespace* as well as the class name. Like \Drupal\something\something\something\DrupalEntityControllerInterface. Must start with a backslash.
Comment #10
cs_shadow CreditAttribution: cs_shadow commented@jhodgdon, I'm not entirely sure who namespaces work. This is what I can make out, please tell me if i'm right:
DrupalEntityControllerInterface
is in the file 'includes/entity.inc'.Thanks for your time.
Comment #11
jhodgdonNot quite. The easiest way to find the namespace for a class/interface is to go to api.drupal.org and search. For this one this takes you to:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!EntityCont...
Right near the top, it says the namespace is:
Drupal\Core\Entity
Or you can find the file that defines the class/interface, and there will be a PHP "namespace" declaration at the top.
So in this case, the fully-qualified namespaced name would be:
\Drupal\Core\Entity\Drupal\Entity\ControllerInterface
For more on namespaces:
http://www.php.net/manual/en/language.namespaces.rationale.php
Comment #12
David_Rothstein CreditAttribution: David_Rothstein commentedThis is Drupal 7 - there are no namespaces :)
Comment #13
jhodgdonOh sorry, didn't notice that!
Ok then, the patch in #7 is OK, except that the first line should start with "Gets" and not "Get".
Comment #14
cs_shadow CreditAttribution: cs_shadow commentedChanged 'Get' to 'Gets'. This patch should fix it at last.
Comment #15
jhodgdonThanks! This looks fine. Committed to 7.x.