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.

CommentFileSizeAuthor
#14 interdiff-7-14.txt351 bytescs_shadow
#14 drupal-missing_@return-2245057-14.patch553 bytescs_shadow
#7 interdiff-3-7.txt467 bytescs_shadow
#7 drupal-missing_@return-2245057-7.patch552 bytescs_shadow
#3 interdiff-1-3.txt540 bytescs_shadow
#3 drupal-missing_@return-2245057-3.patch553 bytescs_shadow
#1 drupal-missing_@return-2245057-1.patch459 bytescs_shadow
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

cs_shadow’s picture

cs_shadow CreditAttribution: cs_shadow commented
Status: Active » Needs review
FileSize
drupal-missing_@return-2245057-1.patch459 bytes

Attached is a patch that adds the '@return '. Any suggestions regarding the text in the doc block are welcome.

joachim’s picture

joachim CreditAttribution: joachim commented
Status: Needs review » Needs work

Thanks!

You should put the interface on the @return itself, eg:

   * @return DatabaseStatementInterface
   *   A PDO prepared statement ready for its execute() method.

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.

cs_shadow’s picture

cs_shadow CreditAttribution: cs_shadow commented
Status: Needs work » Needs review
FileSize
drupal-missing_@return-2245057-3.patch553 bytes
interdiff-1-3.txt540 bytes

Attaching 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.

joachim’s picture

joachim CreditAttribution: joachim commented
Status: Needs review » Reviewed & tested by the community

Perfect. Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Reviewed & tested by the community » Needs work

After any @tag, our policy is that you need to include the namespace with a class name. Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Also the docs are indented 3 spaces on the line after the @return and it should only be 2.

cs_shadow’s picture

cs_shadow CreditAttribution: cs_shadow commented
FileSize
drupal-missing_@return-2245057-7.patch552 bytes
interdiff-3-7.txt467 bytes

Fixed the indentation issue. Not sure what you meant in #5 because I've already included the name of the interface.

@return DrupalEntityControllerInterface

@jhodgdon, please tell me if I'm missing something.

cs_shadow’s picture

cs_shadow CreditAttribution: cs_shadow commented
Status: Needs work » Needs review
jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Needs work

The @return needs the PHP *Namespace* as well as the class name. Like \Drupal\something\something\something\DrupalEntityControllerInterface. Must start with a backslash.

cs_shadow’s picture

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:

 @return \Drupal\includes\entity\DrupalEntityControllerInterface

DrupalEntityControllerInterface is in the file 'includes/entity.inc'.

Thanks for your time.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Not 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

David_Rothstein’s picture

David_Rothstein CreditAttribution: David_Rothstein commented
Status: Needs work » Needs review

This is Drupal 7 - there are no namespaces :)

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Needs work

Oh 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".

cs_shadow’s picture

cs_shadow CreditAttribution: cs_shadow commented
Status: Needs work » Needs review
FileSize
drupal-missing_@return-2245057-14.patch553 bytes
interdiff-7-14.txt351 bytes

Changed 'Get' to 'Gets'. This patch should fix it at last.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Needs review » Fixed

Thanks! This looks fine. Committed to 7.x.

  • Commit 0a74344 on 7.x by jhodgdon: 
    Issue #2245057 by cs_shadow, joachim: Fix docs for entity_get_controller

Status: Fixed » Closed (fixed)

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