"return" used instead of "@return" in RoleInterface::isAdmin() docblock [#2532616]

API page: https://api.drupal.org/api/drupal/core%21modules%21user%21src%21RoleInte...

Patch attached:

diff --git a/core/modules/user/src/RoleInterface.php b/core/modules/user/src/RoleInterface.php
index 0820db4..0d692b8 100644
--- a/core/modules/user/src/RoleInterface.php
+++ b/core/modules/user/src/RoleInterface.php
@@ -78,9 +78,9 @@ public function isAdmin();
    * Sets the role to be an admin role.
    *
    * @param bool $is_admin
-   *   TRUE, if the role should be an admin role.
+   *   TRUE if the role should be an admin role.
    *
-   * return $this
+   * @return $this
    */
   public function setIsAdmin($is_admin);

Comment	File	Size	Author
	role-interface-docs.patch	534 bytes	TR
	8.0.x: PHP 5.5 & MySQL 5.5 12,891 pass

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Comment #1

TR CreditAttribution: TR commented 14 July 2015 at 02:45

Status:

Active

» Needs review

Comment #2

14 July 2015 at 03:11

Status:

Needs review

» Needs work

The last submitted patch, role-interface-docs.patch, failed testing.

Comment #3

TR CreditAttribution: TR commented 14 July 2015 at 03:50

Status:

Needs work

» Needs review

Bogus test fail.

Comment #5

cilefen CreditAttribution: cilefen commented 14 July 2015 at 13:51

Title:

"return" used instead of "@return" in documentation

» "return" used instead of "@return" in RoleInterface::isAdmin() docblock

Comment #6

cilefen CreditAttribution: cilefen commented 14 July 2015 at 13:51

Title:

"return" used instead of "@return" in RoleInterface::isAdmin() docblock

» "return" used instead of "@return" in RoleInterface::isAdmin docblock

Comment #7

15 July 2015 at 04:37

webchick queued role-interface-docs.patch for re-testing.

Comment #8

xjm

she/her

English

CreditAttribution: xjm at Acquia commented 15 July 2015 at 12:18

Title:	"return" used instead of "@return" in RoleInterface::isAdmin docblock	» "return" used instead of "@return" in RoleInterface::isAdmin() docblock
Status:	Reviewed & tested by the community	» Fixed

This issue only changes documentation, so per https://www.drupal.org/core/beta-changes, this can be completed any time during the Drupal 8 beta phase. Committed and pushed to 8.0.x. Thanks!

Comment #9

15 July 2015 at 12:18

xjm committed 4b8b58a on 8.0.x

Issue #2532616 by TR: "return" used instead of "@return" in...

Comment #10

xjm

she/her

English

CreditAttribution: xjm at Acquia commented 15 July 2015 at 14:05

I've just noticed that other similar patches were made for #2532646: "@return boolean" is wrong, use "@return bool" and #2532618: "return" used instead of "@return" in documentation. Instead of doing this in many small patches going forward, let's just create one patch that fixes all the instances of this in core.

Comment #11

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 15 July 2015 at 14:24

I'm of mixed feelings about that. At least these issues got done. Issues like #2224781: Misc API docs fixes take forever to get right, and issues like ... that one we did recently that fixed all the @file doc blocks... the wholesale ones that are generated by scripts conflict with a lot of patches and are hard to get committed, and in the meantime they go to 100 comments due to rerolls.

So, In some cases, someone saying "Oh I noticed this problem here, here's a small patch" is better because at least it gets done.

Comment #12

xjm

she/her

English

CreditAttribution: xjm at Acquia commented 15 July 2015 at 14:46

Thanks @jhodgdon! In general I agree that there are times to do it one way or the other. From my perspective, the problem with #2224781: Misc API docs fixes is that it doesn't have a single scope. @webchick and I drafted some recommendations about this awhile back that are here:
https://docs.google.com/document/d/1zYDnu45djDBcU87sNgKk15C5XDBYzNHvahoq...