remove_role() - invalid return statement

[tivnet]

Returns WP_Roles::remove_role(), which is void.
To omit the return looks more correct.

[GaryJ]

Looks sensible. No other uses of the remove_role() method or function call in core, and you're right in that the method that the function wraps doesn't return anything anyway.

As a side note about documentation, the use of @return void is no longer part of the inline documentation standard (since the ​discussion a few days ago), so that @return tag could be removed completely if the return keyword is indeed going to be removed as well.

[tivnet]

Replying to GaryJ:

@return void is described as very valid here:
​http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html

There could be cases when we might need to distinguish between @return null and void. Void, of course, is null in reality.

But - I do not have any problem omitting @return void.

[nacin]

I would rather omit @return null and @return void. To me, this indicates a deliberate decision, versus the function just not returning anything at the moment. Over time we have added return values to functions that didn't have them previously. For example, true/false on success.

[tivnet]

Replying to nacin:

In any case, returns should be consistent. It's pretty ugly when a function that should return a string, suddenly in the middle has if(...) return;

Even those methods having $echo = true parameters, in my opinion, should return something if echoed.

if ( $echo )
  echo $var; // returned null, inconsistent
else
  return $var;

I'd write as:

if ( $echo )
  echo $var;

return $var; // consistent, whether you want to use it or not

Anyway, what about my patch? Approved, in general? Because I can submit more like this. Please let me know. Thank you!

[SergeyBiryukov]

Appears to be a copy/paste in [3249].

The patch looks good. If we're removing the value from the docs, omitting the return makes sense.

[SergeyBiryukov]

In 25653:

Remove inaccurate @return value from remove_role(). props tivnet. fixes #25450.