Changeset 30280

Timestamp:

11/08/2014 08:18:50 PM (12 years ago)

Author:

DrewAPicture

Message:

Document default arguments for WP_Comment_Query class as a hash notation.

Props boonebgorges, DrewAPicture.
See #30111.

File:

• trunk/src/wp-includes/comment.php (modified) (1 diff)

trunk/src/wp-includes/comment.php

@@ -291 +291 @@
          *              'post_author__not_in', 'author__in', 'author__not_in', 'post__in',
          *              'post__not_in', 'include_unapproved', 'type__in', and 'type__not_in'
-         *              to $query_vars.
-         *
-         * @param string|array $query_vars
-         * @return int|array
+         *              arguments to $query_vars.
+         *
+         * @param string|array $query_vars {
+         *     Optional. Array or query string of comment query parameters.
+         *
+         *     @type string       $author_email        Comment author email address. Default empty.
+         *     @type array        $author__in          Array of author IDs to include comments for. Default empty.
+         *     @type array        $author__not_in      Array of author IDs to exclude comments for. Default empty.
+         *     @type array        $comment__in         Array of comment IDs to include. Default empty.
+         *     @type array        $comment__not_in     Array of comment IDs to exclude. Default empty.
+         *     @type bool         $count               Whether to return a comment count (true) or array of comment
+         *                                             objects (false). Default false.
+         *     @type array        $date_query          Date query clauses to limit comments by. See {@see WP_Date_Query}.
+         *                                             Default null.
+         *     @type string       $fields              Comment fields to return. Accepts 'ids' for comment IDs only or
+         *                                             empty for all fields. Default empty.
+         *     @type int          $ID                  Currently unused.
+         *     @type array        $include_unapproved  Array of IDs or email addresses of users whose unapproved comments
+         *                                             will be returned by the query regardless of `$status`. Default empty.
+         *     @type int          $karma               Karma score to retrieve matching comments for. Default empty.
+         *     @type string       $meta_key            Include comments with a matching comment meta key. Default empty.
+         *     @type string       $meta_value          Include comments with a matching comment meta value. Requires
+         *                                             `$meta_key` to be set. Default empty.
+         *     @type array        $meta_query          Meta query clauses to limit retrieved comments by.
+         *                                             See {@see WP_Meta_Query}. Default empty.
+         *     @type int          $number              Maximum number of comments to retrieve. Default null (no limit).
+         *     @type int          $offset              Number of comments to offset the query. Used to build LIMIT clause.
+         *                                             Default 0.
+         *     @type string|array $orderby             Comment status or array of statuses. Accepts 'comment_agent',
+         *                                             'comment_approved', 'comment_author', 'comment_author_email',
+         *                                             'comment_author_IP', 'comment_author_url', 'comment_content',
+         *                                             'comment_date', 'comment_date_gmt', 'comment_ID', 'comment_karma',
+         *                                             'comment_parent', 'comment_post_ID', 'comment_type', 'user_id',
+         *                                             'meta_value', 'meta_value_num', or value of $meta_key.
+         *                                              Also accepts false, empty array, or 'none' to disable `ORDER BY`
+         *                                             clause. Default: 'comment_date_gmt'.
+         *     @type string       $order               How to order retrieved comments. Accepts 'ASC', 'DESC'.
+         *                                             Default: 'DESC'.
+         *     @type int          $parent              Parent ID of comment to retrieve children of. Default empty.
+         *     @type array        $post_author__in     Array of author IDs to retrieve comments for. Default empty.
+         *     @type array        $post_author__not_in Array of author IDs *not* to retrieve comments for. Default empty.
+         *     @type int          $post_ID             Currently unused.
+         *     @type int          $post_id             Limit results to those affiliated with a given post ID. Default 0.
+         *     @type array        $post__in            Array of post IDs to include affiliated comments for. Default empty.
+         *     @type array        $post__not_in        Array of post IDs to exclude affiliated comments for. Default empty.
+         *     @type int          $post_author         Comment author ID to limit results by. Default empty.
+         *     @type string       $post_status         Post status to retrieve affiliated comments for. Default empty.
+         *     @type string       $post_type           Post type to retrieve affiliated comments for. Default empty.
+         *     @type string       $post_name           Post name to retrieve affiliated comments for. Default empty.
+         *     @type int          $post_parent         Post parent ID to retrieve affiliated comments for. Default empty.
+         *     @type string       $search              Search term(s) to retrieve matching comments for. Default empty.
+         *     @type string       $status              Comment status to limit results by. Accepts 'hold'
+         *                                             (`comment_status=0`), 'approve' (`comment_status=1`), 'all', or a
+         *                                             custom comment status. Default 'all'.
+         *     @type string|array $type                Include comments of a given type, or array of types. Accepts
+         *                                             'comment', 'pings' (includes 'pingback' and 'trackback'), or any
+         *                                             custom type string. Default empty.
+         *     @type array        $type__in            Include comments from a given array of comment types. Default empty.
+         *     @type array        $type__not_in        Exclude comments from a given array of comment types. Default empty.
+         *     @type int          $user_id             Include comments for a specific user ID. Default empty.
+         * }
+         * @return int|array Array of comments or number of found comments if `$count` is set to true.
          */
         public function query( $query_vars ) {