From e7b465046a859960723744dfb2f3fc5ababfb6a7 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <info@drewapicture.com>
Date: Sat, 8 Nov 2014 20:35:22 +0000
Subject: [PATCH] Cross-reference `WP_Comment_Query::query()` as the location
 for finding information on default arguments for `WP_Comment_Query`.

Also updates the return types on `get_comments()` and `get_approved_comments()`, as an integer can also be returned if the `$count` argument is true.

Fixes #30111.

Built from https://develop.svn.wordpress.org/trunk@30281


git-svn-id: http://core.svn.wordpress.org/trunk@30281 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/comment.php         | 15 ++++++++-------
 wp-includes/default-widgets.php |  2 +-
 wp-includes/version.php         |  2 +-
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index c0f4d2733f..a3e4ac1b4b 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -131,9 +131,10 @@ function check_comment($author, $email, $url, $comment, $user_ip, $user_agent, $
  * @since 4.1.0 Refactored to leverage {@see WP_Comment_Query} over a direct query.
  *
  * @param  int   $post_id The ID of the post.
- * @param  array $args    Optional. See {@see WP_Comment_Query} for information
+ * @param  array $args    Optional. See {@see WP_Comment_Query::query()} for information
  *                        on accepted arguments.
- * @return array $comments The approved comments.
+ * @return int|array $comments The approved comments, or number of comments if `$count`
+ *                             argument is true.
  */
 function get_approved_comments( $post_id = 0, $args = array() ) {
 	$defaults = array(
@@ -211,15 +212,13 @@ function get_comment(&$comment, $output = OBJECT) {
  *
  * The comment list can be for the blog as a whole or for an individual post.
  *
- * The list of comment arguments are 'status', 'orderby', 'comment_date_gmt',
- * 'order', 'number', 'offset', and 'post_id'.
- *
  * @since 2.7.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param mixed $args Optional. Array or string of options to override defaults.
- * @return array List of comments.
+ * @param string|array $args Optional. Array or string of arguments. See {@see WP_Comment_Query::query()}
+ *                           for information on accepted arguments. Default empty.
+ * @return int|array List of comments or number of found comments if `$count` argument is true.
  */
 function get_comments( $args = '' ) {
 	$query = new WP_Comment_Query;
@@ -229,6 +228,8 @@ function get_comments( $args = '' ) {
 /**
  * WordPress Comment Query class.
  *
+ * See {@see WP_Comment_Query::query()} for accepted arguments.
+ *
  * @since 3.1.0
  */
 class WP_Comment_Query {
diff --git a/wp-includes/default-widgets.php b/wp-includes/default-widgets.php
index 7ad17f3c1e..1bdadd8ee2 100644
--- a/wp-includes/default-widgets.php
+++ b/wp-includes/default-widgets.php
@@ -849,7 +849,7 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 		 *
 		 * @since 3.4.0
 		 *
-		 * @see get_comments()
+		 * @see WP_Comment_Query::query() for information on accepted arguments.
 		 *
 		 * @param array $comment_args An array of arguments used to retrieve the recent comments.
 		 */
diff --git a/wp-includes/version.php b/wp-includes/version.php
index c1ab546b9b..62e42c3572 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.1-alpha-30280';
+$wp_version = '4.1-alpha-30281';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.