[wp-trac] [WordPress Trac] #24900: PHPDocs for $wp_admin_bar in admin-bar.php

[WordPress Trac]

#24900: PHPDocs for $wp_admin_bar in admin-bar.php
--------------------------+---------------------
 Reporter:  jeremyfelt    |       Owner:
     Type:  defect (bug)  |      Status:  closed
 Priority:  normal        |   Milestone:  3.7
Component:  Inline Docs   |     Version:  3.1
 Severity:  normal        |  Resolution:  fixed
 Keywords:  has-patch     |
--------------------------+---------------------
Changes (by nacin):

 * status:  reopened => closed
 * resolution:   => fixed


Comment:

 Replying to [comment:6 toscho]:
 > These doc blocks are wrong: no function in this file requires an
 instance of `WP_Admin_Bar`. To make the doc blocks true, we have to add a
 type hint like this:
 >
 > {{{
 > function wp_admin_bar_search_menu( WP_Admin_Bar $wp_admin_bar ) {
 > }}}
 >
 > Currently, these functions accept any class with a matching set of
 public methods, no matter what they do. Doc blocks should never lie, this
 is sloppy code.

 I disagree. We cannot type-hint here for historical reasons. But even if
 we could, I still disagree. Of all the PHPDoc standards I can find, none
 say they must match a type-hint. [https://github.com/phpDocumentor/fig-
 standards/blob/master/proposed/phpdoc.md#813-param The ongoing FIG
 standards] specifically say "When provided it MUST contain a "Type" to
 indicate what is expected". '''Expected'''. Not enforced by a type-hint,
 just expected.

 I'm totally fine with doc blocks "lying" in order to documented
 '''expected''' behavior. In my opinion, "these functions accept any class
 with a matching set of public methods" is rrelevant and invalid.

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