[wp-trac] [WordPress Trac] #32974: Duplicate @since tags

[WordPress Trac]

#32974: Duplicate @since tags
-----------------------------+-----------------------------
 Reporter:  johnjamesjacoby  |      Owner:
     Type:  defect (bug)     |     Status:  new
 Priority:  normal           |  Milestone:  Awaiting Review
Component:  General          |    Version:
 Severity:  normal           |   Keywords:  2nd-opinion
  Focuses:  docs             |
-----------------------------+-----------------------------
 According to the
 [http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.since.pkg.html
 official PHPDoc specifications] `@since` tags should be used as:

 > This function has been a part of this package since version 2.0

 ...but there are many places in WordPress core where `@since` is being
 misused to instead indicate:

 > This function changed in version 2.0 to also do this other thing

 (Check out [https://core.trac.wordpress.org/browser/trunk/src/wp-
 includes/user.php?annotate=blame#L256 count_user_posts()] as an example.)

 I don't see another obvious tag that addresses this need, but `@internal`
 might work well enough as according to the spec, it says:

 > In both cases, the intent is to allow the creation of two sets of
 documentation, one for public use, and the other for a subset of
 developers, either the project developers or those who wish to extend the
 project. In essence, it allows the creation of both user-level and
 programmer-level documentation from the same source, and is one of
 phpDocumentor's most useful features.

 If methods or functions are refactored to the point of necessitating a
 second `@since` tag, that indicates (to me) that a new function or method
 is likely necessary, which would accommodate it's own `@since` tag amongst
 others.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/32974>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform