WordPress.org

Make WordPress Core

Opened 3 years ago

Last modified 2 years ago

#44450 new defect (bug)

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

Reported by: subrataemfluence Owned by:
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: Widgets Keywords: has-patch needs-refresh
Focuses: docs, coding-standards Cc:

Description

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.

Attachments (2)

44450.diff (4.1 KB) - added by subrataemfluence 3 years ago.
Proposed patch
44450-2.diff (4.1 KB) - added by subrataemfluence 3 years ago.
Please ignore the last one. Wrong patch uploaded by mistake. Uploading modified patch.

Download all attachments as: .zip

Change History (14)

@subrataemfluence
3 years ago

Proposed patch

@subrataemfluence
3 years ago

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

#1 @subrataemfluence
3 years ago

  • Keywords has-patch added; needs-patch removed

#2 @subrataemfluence
3 years ago

  • Summary changed from Functions/methods do not return any value in classes should use @return void. to Functions/methods do not return any value in classes should use @return void in method doc

#3 @netweb
3 years ago

  • Milestone changed from Awaiting Review to 5.0

#4 in reply to: ↑ description @pbiron
3 years ago

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!

#5 @pento
3 years ago

  • Milestone changed from 5.0 to 5.1

#6 @pento
3 years ago

  • Keywords needs-refresh added

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

#7 @pento
3 years ago

  • Milestone changed from 5.1 to Future Release
  • Version trunk deleted

#8 @subrataemfluence
3 years ago

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

#9 @pento
3 years ago

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?

#10 @DrewAPicture
3 years ago

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.

#11 @szepe.viktor
2 years ago

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

Last edited 2 years ago by szepe.viktor (previous) (diff)

#12 @subrataemfluence
2 years ago

@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!

Note: See TracTickets for help on using tickets.