[wp-trac] [WordPress Trac] #53399: Docblock improvements for WP 5.9

[WordPress Trac]

#53399: Docblock improvements for WP 5.9
----------------------------+---------------------
 Reporter:  desrosj         |       Owner:  (none)
     Type:  task (blessed)  |      Status:  new
 Priority:  normal          |   Milestone:  5.9
Component:  General         |     Version:
 Severity:  normal          |  Resolution:
 Keywords:                  |     Focuses:  docs
----------------------------+---------------------

Comment (by SergeyBiryukov):

 Replying to [comment:31 johnbillion]:
 > To be honest I don't think these comments provide value to a developer.
 Whether or not a function internally wraps another one is of no
 consequence if it doesn't affect its external API. I'd be in favour of
 removing them.

 I think this falls under the last point in
 [https://developer.wordpress.org/coding-standards/inline-documentation-
 standards/php/#since-section-changelogs @since Section (Changelogs)]:
 > If significant changes have been made to a function, hook, class, or
 method, additional `@since` tags, versions, and descriptions should be
 added to provide a changelog for that function.
 >
 > “Significant changes” include but are not limited to:
 >
 > * Adding new arguments or parameters
 > * Required arguments becoming optional
 > * Changing default/expected behaviors
 > * Functions or methods becoming wrappers for new APIs

 Personally, I see some value in being able to tell if there is another
 function that can be used as a suitable replacement, and in which version
 the change was made.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/53399#comment:32>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform