[wp-trac] [WordPress Trac] #32139: Add PHPDoc for all global $wp_query in /wp-includes/query.php

[WordPress Trac]

#32139: Add PHPDoc for all global $wp_query in /wp-includes/query.php
--------------------------+-----------------------------
 Reporter:  MikeSchinkel  |      Owner:
     Type:  enhancement   |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  Query         |    Version:  trunk
 Severity:  normal        |   Keywords:
  Focuses:  docs          |
--------------------------+-----------------------------
 The attached patch will add PHPDoc comments for all instances of `global
 $wp_query` in `/wp-includes/query.php`. This patch does nothing other than
 add/change documentation; it has no effect on runtime logic.

 In addition to improving code documentation this change will also benefit
 developers using PhpStorm:

 1. Method calls will no longer be flagged as "not found" in PhpStorm

 2. Developers will be able to use the "Navigate To" functionality found in
 PhpStorm to jump directly to the declarations of the `WP_Query` method
 while using PhpStorm.

 In addition to PHPDoc for `$wp_query`  PhpStorm flagged several functions
 that had `return` statements where no value was being returned by the
 expression because it the functions where returning the value of a `void`
 method call. I removed the `return` statements and any erroneous `@return`
 PHPDoc comments from these three (3) functions:

 1. `set_query_var()`
 2. `rewind_posts()`
 3. `the_comment()`

 After these changes PhpStorm no longer flags any errors in the file and is
 now ''(fully?)'' navigable.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/32139>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform