[wp-trac] [WordPress Trac] #24900: PHPDocs for $wp_admin_bar in admin-bar.php
WordPress Trac
noreply at wordpress.org
Thu Sep 5 20:56:58 UTC 2013
#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
More information about the wp-trac
mailing list