Changeset 49700

Timestamp:

11/26/2020 05:02:02 PM (3 years ago)

Author:

johnbillion

Message:

Docs: Corrections and improvements to docs for properties of the WP_Query class.

This also adds additional type hinting inside some methods to help IDEs.

See #51800

File:

• trunk/src/wp-includes/class-wp-query.php (modified) (15 diffs)

trunk/src/wp-includes/class-wp-query.php

@@ -77 +77 @@
 
     /**
-     * Get post database query.
+     * SQL for the database query.
      *
      * @since 2.0.1
@@ -85 +85 @@
 
     /**
-     * List of posts.
+     * Array of post objects or post IDs.
      *
      * @since 1.5.0
-     * @var array
+     * @var WP_Post[]|int[]
      */
     public $posts;
@@ -119 +119 @@
      * The current post.
      *
+     * This property does not get populated when the `fields` argument is set to
+     * `ids` or `id=>parent`.
+     *
      * @since 1.5.0
-     * @var WP_Post
+     * @var WP_Post|null
      */
     public $post;
@@ -128 +131 @@
      *
      * @since 2.2.0
-     * @var array
+     * @var WP_Comment[]
      */
     public $comments;
@@ -149 +152 @@
 
     /**
-     * Current comment ID.
+     * Current comment object.
      *
      * @since 2.2.0
-     * @var int
+     * @var WP_Comment
      */
     public $comment;
@@ -2661 +2664 @@
             $comments = (array) $wpdb->get_results( "SELECT $distinct {$wpdb->comments}.* FROM {$wpdb->comments} $cjoin $cwhere $cgroupby $corderby $climits" );
             // Convert to WP_Comment.
+            /** @var WP_Comment[] */
             $this->comments      = array_map( 'get_comment', $comments );
             $this->comment_count = count( $this->comments );
@@ -2945 +2949 @@
          * @since 4.6.0
          *
-         * @param array|null $posts Return an array of post data to short-circuit WP's query,
-         *                          or null to allow WP to run its normal queries.
-         * @param WP_Query   $this  The WP_Query instance (passed by reference).
+         * @param WP_Post[]|int[]|null $posts Return an array of post data to short-circuit WP's query,
+         *                                    or null to allow WP to run its normal queries.
+         * @param WP_Query             $this  The WP_Query instance (passed by reference).
          */
         $this->posts = apply_filters_ref_array( 'posts_pre_query', array( null, &$this ) );
@@ -2956 +2960 @@
             }
 
+            /** @var int[] */
             $this->posts      = array_map( 'intval', $this->posts );
             $this->post_count = count( $this->posts );
@@ -2971 +2976 @@
             $this->set_found_posts( $q, $limits );
 
+            /** @var int[] */
             $r = array();
             foreach ( $this->posts as $key => $post ) {
@@ -3031 +3037 @@
         // Convert to WP_Post objects.
         if ( $this->posts ) {
+            /** @var WP_Post[] */
             $this->posts = array_map( 'get_post', $this->posts );
         }
@@ -3067 +3074 @@
             $comments         = $wpdb->get_results( $comments_request );
             // Convert to WP_Comment.
+            /** @var WP_Comment[] */
             $this->comments      = array_map( 'get_comment', $comments );
             $this->comment_count = count( $this->comments );
@@ -3196 +3204 @@
             $this->post_count = count( $this->posts );
 
+            /** @var WP_Post[] */
             $this->posts = array_map( 'get_post', $this->posts );
 
@@ -3202 +3211 @@
             }
 
+            /** @var WP_Post */
             $this->post = reset( $this->posts );
         } else {
@@ -3282 +3292 @@
         $this->current_post++;
 
+        /** @var WP_Post */
         $this->post = $this->posts[ $this->current_post ];
         return $this->post;
@@ -3375 +3386 @@
         $this->current_comment++;
 
+        /** @var WP_Comment */
         $this->comment = $this->comments[ $this->current_comment ];
         return $this->comment;