[wp-trac] [WordPress Trac] #14921: WP_Dependencies is tagged as external but is core package

[WordPress Trac]

#14921: WP_Dependencies is tagged as external but is core package
--------------------------+-------------------------------------------------
 Reporter:  hakre         |       Owner:                 
     Type:  defect (bug)  |      Status:  new            
 Priority:  normal        |   Milestone:  Awaiting Review
Component:  Inline Docs   |     Version:  3.0            
 Severity:  normal        |    Keywords:                 
--------------------------+-------------------------------------------------
Changes (by hakre):

  * component:  General => Inline Docs


Comment:

 Replying to [comment:2 nacin]:
 > These were extracted out of !WordPress core and are now considered
 external packages as part of the BackPress library. Despite the fact that
 we maintain it, I find @package fine here.

 I can not consider files with wordpress core code that are still
 maintained in wordpress (and not BackPress) as external packages. And I
 doubt that there is such a consideration. That would turn the principles
 of Upstream upside-down.

 BackPress is very closely to !WordPress core, but that does not mean that
 it normally re-labels wordpress package files ''in'' !WordPress.

 I'm even quite sure that this misalignment in these five files has been
 done in error. There are other files that are in BackPress library and in
 !WordPress as well which do not @package this way. It are just those five
 files that are out of the row. For no special need btw.

 >
 > At most, I would suggest:
 >
  {{{
  @since BackPress r74
  @since WordPress 2.6.0
  }}}

 This can create problems with PHPdocs. @since by design contains the
 version of @package
 ([http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.since.pkg.html
 manual]):

 > Use @since to document revisions, as in "This function has been a part
 of this package since version 2.0"

 Next to that, it mixes responsibilities. The BackPress project itself
 needs to keep track for the various -Press (bbPress, GlotPress) sister
 projects. That's nothing we can and should do in the wordpress project.

 ----

 Generally spoken: If it's an external, it should be treated as an
 external. If it's not it's not.

 Considerations that make some files external by PHPDocs while factually
 being plain !WordPress code is underminig PHPDocs and is reducing and even
 hindering its use.

-- 
Ticket URL: <http://core.trac.wordpress.org/ticket/14921#comment:3>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software