Functions/methods do not return any value in classes should use @return void in method doc

[subrataemfluence]

Several classes inside wp-includes/widgets directory are missing @return void in function docs which are echo-ing output but not returning any value.

There are many other areas in the core which are using this approach. We need to be consistent.

[subrataemfluence]

Proposed patch

[subrataemfluence]

Please ignore the last one. Wrong patch uploaded by mistake. Uploading modified patch.

[pbiron]

Replying to subrataemfluence:

There are many other areas in the core which are using this approach. We need to be consistent.

The vast majority of core does not use @return void when it applies, presumably because the ​DocBlock Formating: Functions & Class Methods section of the handbook specifically says:

@return: Should contain all possible return types, and a description for each. Use a period at the end. Note: @return void should not be used outside of the default bundled themes.

But I whole-heartedly agree that @return void should be used everywhere it applies!

p.s. thank you so much for all of the DocBlock-related tickets you've been creating lately!

[pento]

44450-2.diff​ needs to be updated to only add @return void to anywhere in the bundled themes missing it.

[subrataemfluence]

@pento would you mind to explain a bit more please?

[pento]

Actually, in #27098 we removed all of the @return void comments from the themes.

@DrewAPicture: What's the current state of this practice for docblocks?

[DrewAPicture]

The current standard for omitting @return void still stands in core, though with the acceptance of void as a type in PHP7+ I'd be in favor of discussing an optional reversal of the current policy of omission.

I know the issue has been raised by @jrf previously (in favor of requiring @return notations on all the things) though I'm not sure I'm in favor of swinging from one extreme to another. That's a lot of code to update in core and assuming the wpcs follows suit, anybody who's been following that lead.

I'll close by simply saying that Idon't love the idea of requiring things purely in the name of completeness. We currently omit @return notations for things that don't return and require them for things that do. I'm not sure what virtue there is in documenting that nothing gets returned.

[szepe.viktor]

Maybe @return string|void is much more important than the above things.

Would it be possible to change all void+some type returns to null+some type?

See ​https://github.com/phpstan/phpstan/issues/2061#issuecomment-480234535

[subrataemfluence]

@DrewAPicture I understand what you said. But it is not only about adding @return void just because of completeness. Rather Docblocks should probably be written in such a manner so that it gives a complete overview of the function itself.

For example, we use parameter types along with their descriptions, a description of the function itself to explain what a function actually does. And we do all these only to make the objective of a function easily understandable without even going through its body. And my personal feeling is return type should also fall in this category.

I do understand that it would be a lot of update in core coding but having a return type even it is void will make things more logical from a developer's point of view.

However, since @return void has been removed in purpose, I don't think it will be taken back anymore. I only wanted to explain the way how I see it.

Thank you!