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

[WordPress Trac]

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

Comment (by DrewAPicture):

 [attachment:WP_Query-hook-docs.2.diff]:
 Overall:
 * Any function references in descriptions need parenthesis, e.g.
 s/parse_query/parse_query()
 * I'm not a big fan of this wording: "Fires actions to be run after ...".
 It ''is'' an action. "Fires after ..." says the same thing without
 ambiguity, and is consistent with the suggested language for actions.
 * "refrence" is misspelled many times, probably from copy/pasta
 * s/portion/clause in many short descriptions
 * There's a lot of copy pasta in here. The point of documenting the
 individual hooks is to both differentiate them from each other and provide
 valuable, unique information about each specific hook. It's also important
 to provide context. View each hook as independent of the other hooks, even
 independent of the file it's in.

 `pre_get_posts` hook:
 * The description is very literal, and kind of incorrect. If
 `$this->parse_query()` has already run, it's hardly "before `get_posts()`
 actually begins.
 * Worth noting in a long description that many/most conditional tags
 aren't available yet for this hook. For instance, `is_main_query()`/#23329

 `posts_where_paged`, `posts_groupby`, `posts_join_paged`, `posts_orderby`,
 `posts_distinct`, `post_limits`, `posts_fields`, 'posts_clauses` filters:
 * Need to specify that these are specifically for use when "paged" in each
 hook's description

 `posts_selection` hook:
 * Assign the concatenated variables to `$selection` before the doc starts.
 '''We need to be very careful about documenting variables that don't
 exist.'''
 * Since the parameter is a concatenation of the clauses, we need to spell
 out which clauses comprise the parameter, either in the parameter
 description, or a long description for the hook doc.

 `posts_where_request`, `posts_groupby_request`, `posts_join_request`,
 `posts_orderby_request`, `posts_distinct_request`, `posts_fields_request`,
 `post_limits_request`, `posts_clauses_request` filters:
 * Specify that these filters are for use by caching plugins in each hook's
 description

 `posts_clauses_request` filter:
 * Assign `compact( $pieces )` to `$pieces` before the doc. Again, avoid
 nonexistent variables.

 `posts_request` filter:
 * Assign `$this->request` to `$request`.

 `split_the_query` filter:
 * Description is pretty vague. Perhaps explain what splitting the query
 actually means.

 `posts_request_ids` filter:
 * Should specify that it's a SQL request

 `posts_results` filter:
 * Assign `$this->posts` to `$posts_results` and change the referenced
 variable in the parameter doc

 `the_preview` filter:
 * Assign `$this->posts[0]` to `$post_preview` and change the referenced
 variable in the parameter line (don't want to stomp the `$post` global,
 afterall

 `the_posts` filter:
 * Assign `$this->posts` to `$the_posts` and change the referenced variable
 in the parameter doc

 `found_posts_query` filter:
 * Assign `'SELECT FOUND_ROWS()'` to `$found_posts_query` and change the
 referenced variable in the parameter doc

 `found_posts` filter:
 * Assign `$this->found_posts` to `$found_posts`

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