[wp-trac] [WordPress Trac] #25514: Hook Docs: wp-includes/query.php

[WordPress Trac]

#25514: Hook Docs: wp-includes/query.php
--------------------------+------------------------------
 Reporter:  dougwollison  |       Owner:  DrewAPicture
     Type:  enhancement   |      Status:  reviewing
 Priority:  normal        |   Milestone:  Awaiting Review
Component:  Inline Docs   |     Version:
 Severity:  normal        |  Resolution:
 Keywords:  needs-patch   |
--------------------------+------------------------------

Comment (by DrewAPicture):

 Replying to [comment:6 dougwollison]:
 > Done, however in terms of documenting variables that "don't exist", it
 still goes back to the fact that we're documenting how the hook is used;
 the exact name of the parameter doesn't matter, as it's getting passed to
 another function that may use it's only naming for it.
 >
 > We almost don't need to name the variables at all; just the type and a
 description. It's more like a @return tag than a @param tag in some ways.

 Unfortunately, we can't just look at this from the perspective of "<this
 thing> will be parsed, so it doesn't really matter."

 As pointed out by @tivnet in another ticket (can't find the number), we
 need be careful about 1) declaring types for nonexistent variables, 2)
 redeclaring new types for existing variables in doc blocks, even if they
 are for hooks, because they can cause validation errors.

 We're never going to be able to circumvent all of these cases, but taking
 a proactive approach to avoiding them is probably for the best.

 > PHPDoc wasn't really written with this particular use in mind.

 This is correct. Unfortunately, !WordPress has an action and filter
 architecture, and this is the best method we've been able to come up with
 for documenting hooks and filters.

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