[wp-trac] [WordPress Trac] #61307: Wrong variable name in filter documentation

[WordPress Trac]

#61307: Wrong variable name in filter documentation
-----------------------------------------+------------------------
 Reporter:  david.binda                  |       Owner:  audrasjb
     Type:  defect (bug)                 |      Status:  reviewing
 Priority:  normal                       |   Milestone:  6.6
Component:  Query                        |     Version:  6.0
 Severity:  normal                       |  Resolution:
 Keywords:  has-patch changes-requested  |     Focuses:  docs
-----------------------------------------+------------------------
Changes (by hellofromTonya):

 * keywords:  has-patch => has-patch changes-requested


Comment:

 Interesting. Looking at the history:

 * [52974] changed `$pieces` to `$clauses`.
 * [53375] for `WP_Query`, reverted part of the change for `WP_Query` ->
 the individual query pieces array gets assigned to `$pieces` and `compact(
 $pieces )` represents the `$clauses`.
 * [53376] did the same treatment in `WP_Comment_Query`,
 `WP_Network_Query`, `WP_Site_Query`, and `WP_Term_Query`.

 Each of these queries are now consistent, which is good.

 >IIRC, this part of the DocBlock was not reverted back to `$pieces` in
 [53376] specifically to avoid confusion. My thinking was that $clauses
 represents `compact( $pieces )`, which gets passed to the filters, not
 `$pieces` itself.
 >
 >So reverting this to `$pieces` would be more confusing for me, but I'm
 curious to see what others think.

 I agree with @SergeyBiryukov and @ironprogrammer. Pieces and clauses are 2
 different things. The naming is consistent and aligns well IMO to these 2
 different purposes.

 >The DocBlock at https://core.trac.wordpress.org/browser/trunk/src/wp-
 includes/class-wp-query.php#L2934 is verbose in describing what $clauses
 represents. Would it help for the other filter calls to include these
 details to avoid ambiguity?

 I agree with @ironprogrammer. The filter's DocBlock for the others should
 also receive the more verbose version for the `$clauses`. Doing so keeps
 them consistent, helps with understanding, and should avoid confusion.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/61307#comment:8>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform