Twenty Seventeen: Missing @return in comment documentation

[ndoublehwp]

In the comment docs of function

twentyseventeen_video_controls()

, the @return is missing

[ndoublehwp]

In the comment docs of function twentyseventeen_video_controls(), the @return is missing

[audrasjb]

Hi ndoublehwp,
Nice catch ;)
Here is a patch to include inline doc before this function.

Regards,
Jb

[audrasjb]

Add inline doc before the function

[truongwp]

@audrasjb I think we don't need $settings in @return line

[audrasjb]

@truongwp ha? Ok. Is it better now? This is my very first step in inline doc so please let me know if anything is wrong :)

[audrasjb]

remove $settings from return inline doc

[xkon]

@truongwp, usually we state what returns though. So shouldn't it actually be @return Settings or something similar on this instance?

---

Edit: @truongwp is correct. I guess I've missed it before... x_x

@audrasjb check this : ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#4-hooks-actions-and-filters

[audrasjb]

So @xkon @truongwp if I not misunderstand the handbook, there should not be any @return in inline documentation because filters always return their first parameter. Am I right?

[xkon]

According to the Handbook

Quoting:

Note that @return is not used for hook documentation, because action hooks return nothing, and filter hooks always return their first parameter.

So yes the original documentation was fine as it was since this is a filter function.

[truongwp]

Hi,

This is inline docs for a function. Please see the example here: ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#1-functions-class-methods

@return type Description. or @return type are correct, not @return type $var Description. or @return Description.

[SergeyBiryukov]

In 41780:

Twenty Seventeen: Add missing @return tag for twentyseventeen_video_controls().

Props ndoublehwp, audrasjb.
Fixes #41927.