Docs: Improve the documentation for parameters which accept `OBJECT`, `ARRAY_A`, and `ARRAY_N` as parameters.

See #37770

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


git-svn-id: http://core.svn.wordpress.org/trunk@39128 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/bookmark.php

@@ -14,7 +14,8 @@
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param int|stdClass $bookmark
- * @param string $output Optional. Either OBJECT, ARRAY_N, or ARRAY_A constant
+ * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                       an stdClass object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string $filter Optional, default is 'raw'.
  * @return array|object|null Type returned depends on $output value.
  */
@@ -300,10 +301,10 @@ function get_bookmarks( $args = '' ) {
  *
  * @since 2.3.0
  *
- * @param object|array $bookmark Bookmark row
+ * @param stdClass|array $bookmark Bookmark row
  * @param string $context Optional, default is 'display'. How to filter the
  *		fields
- * @return object|array Same type as $bookmark but with fields sanitized.
+ * @return stdClass|array Same type as $bookmark but with fields sanitized.
  */
 function sanitize_bookmark($bookmark, $context = 'display') {
 	$fields = array('link_id', 'link_url', 'link_name', 'link_image', 'link_target', 'link_category',

wp-includes/category.php

@@ -82,7 +82,8 @@ function get_categories( $args = '' ) {
  * @since 1.5.1
  *
  * @param int|object $category Category ID or Category row object
- * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to a
+ *                       WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string $filter Optional. Default is raw or no WordPress defined filter will applied.
  * @return object|array|WP_Error|null Category data in type defined by $output parameter.
  *                                    WP_Error if $category is empty, null if it does not exist.
@@ -114,8 +115,9 @@ function get_category( $category, $output = OBJECT, $filter = 'raw' ) {
  *
  * @param string $category_path URL containing category slugs.
  * @param bool   $full_match    Optional. Whether full path should be matched.
- * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string $output        Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- * @return object|array|WP_Error|void Type is based on $output value.
+ *                              a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
+ * @return WP_Term|array|WP_Error|null Type is based on $output value.
  */
 function get_category_by_path( $category_path, $full_match = true, $output = OBJECT ) {
 	$category_path = rawurlencode( urldecode( $category_path ) );
@@ -296,10 +298,11 @@ function get_tags( $args = '' ) {
  *
  * @since 2.3.0
  *
- * @param int|object $tag
+ * @param int|WP_Term|object $tag    A tag ID or object.
- * @param string $output Optional. Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string             $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                                   a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string             $filter Optional. Default is raw or no WordPress defined filter will applied.
- * @return object|array|WP_Error|null Tag data in type defined by $output parameter. WP_Error if $tag is empty, null if it does not exist.
+ * @return WP_Term|array|WP_Error|null Tag data in type defined by $output parameter. WP_Error if $tag is empty, null if it does not exist.
  */
 function get_tag( $tag, $output = OBJECT, $filter = 'raw' ) {
 	return get_term( $tag, 'post_tag', $output, $filter );

wp-includes/comment.php

@@ -170,7 +170,8 @@ function get_approved_comments( $post_id, $args = array() ) {
  * @global WP_Comment $comment
  *
  * @param WP_Comment|string|int $comment Comment to retrieve.
- * @param string $output Optional. OBJECT or ARRAY_A or ARRAY_N constants.
+ * @param string                $output  Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                                       a WP_Comment object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @return WP_Comment|array|null Depends on $output value.
  */
 function get_comment( &$comment = null, $output = OBJECT ) {

wp-includes/post.php

@@ -401,8 +401,8 @@ function _wp_relative_upload_path( $path ) {
  * @global WP_Post $post
  *
  * @param mixed  $args   Optional. User defined arguments for replacing the defaults. Default empty.
- * @param string $output Optional. Constant for return type. Accepts OBJECT, ARRAY_A, ARRAY_N.
+ * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- *                       Default OBJECT.
+ *                       a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @return array Array of children, where the type of each element is determined by $output parameter.
  *               Empty array on failure.
  */
@@ -505,8 +505,8 @@ function get_extended( $post ) {
  * @global WP_Post $post
  *
  * @param int|WP_Post|null $post   Optional. Post ID or post object. Defaults to global $post.
- * @param string           $output Optional, default is Object. Accepts OBJECT, ARRAY_A, or ARRAY_N.
+ * @param string           $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- *                                 Default OBJECT.
+ *                                 a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string           $filter Optional. Type of filter to apply. Accepts 'raw', 'edit', 'db',
  *                                 or 'display'. Default 'raw'.
  * @return WP_Post|array|null Type corresponding to $output on success or null on failure.
@@ -2863,8 +2863,10 @@ function wp_get_post_terms( $post_id = 0, $taxonomy = 'post_tag', $args = array(
  * @see get_posts()
  *
  * @param array  $args   Optional. Arguments to retrieve posts. Default empty array.
- * @param string $output     Optional. Type of output. Accepts ARRAY_A or ''. Default ARRAY_A.
+ * @param string $output Optional. The required return type. One of OBJECT or ARRAY_A, which correspond to
- * @return array|false Associative array if $output equals ARRAY_A, array or false if no results.
+ *                       a WP_Post object or an associative array, respectively. Default ARRAY_A.
+ * @return array|false Array of recent posts, where the type of each element is determined by $output parameter.
+ *                     Empty array on failure.
  */
 function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) {
 
@@ -4190,11 +4192,11 @@ function get_all_page_ids() {
  * @deprecated 3.5.0 Use get_post()
  *
  * @param mixed  $page   Page object or page ID. Passed by reference.
- * @param string $output Optional. What to output. Accepts OBJECT, ARRAY_A, or ARRAY_N.
+ * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- *                       Default OBJECT.
+ *                       a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string $filter Optional. How the return value should be filtered. Accepts 'raw',
  *                       'edit', 'db', 'display'. Default 'raw'.
- * @return WP_Post|array|null WP_Post on success or null on failure.
+ * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
  */
 function get_page( $page, $output = OBJECT, $filter = 'raw') {
 	return get_post( $page, $output, $filter );
@@ -4208,10 +4210,10 @@ function get_page( $page, $output = OBJECT, $filter = 'raw') {
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param string       $page_path Page path.
- * @param string       $output    Optional. Output type. Accepts OBJECT, ARRAY_N, or ARRAY_A.
+ * @param string       $output    Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- *                                Default OBJECT.
+ *                                a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string|array $post_type Optional. Post type or array of post types. Default 'page'.
- * @return WP_Post|array|void WP_Post on success.
+ * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
  */
 function get_page_by_path( $page_path, $output = OBJECT, $post_type = 'page' ) {
 	global $wpdb;
@@ -4300,10 +4302,10 @@ function get_page_by_path( $page_path, $output = OBJECT, $post_type = 'page' ) {
  * @global wpdb $wpdb WordPress database abstraction object.
  *
  * @param string       $page_title Page title
- * @param string       $output     Optional. Output type. OBJECT, ARRAY_N, or ARRAY_A.
+ * @param string       $output     Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- *                                 Default OBJECT.
+ *                                 a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string|array $post_type  Optional. Post type or array of post types. Default 'page'.
- * @return WP_Post|array|void WP_Post on success or null on failure
+ * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
  */
 function get_page_by_title( $page_title, $output = OBJECT, $post_type = 'page' ) {
 	global $wpdb;

wp-includes/revision.php

@@ -321,9 +321,10 @@ function _wp_put_post_revision( $post = null, $autosave = false ) {
  * @since 2.6.0
  *
  * @param int|WP_Post $post   The post ID or object.
- * @param string      $output Optional. OBJECT, ARRAY_A, or ARRAY_N.
+ * @param string      $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                            a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string      $filter Optional sanitation filter. See sanitize_post().
- * @return WP_Post|array|null Null if error or post object if success.
+ * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
  */
 function wp_get_post_revision(&$post, $output = OBJECT, $filter = 'raw') {
 	if ( !$revision = get_post( $post, OBJECT, $filter ) )

wp-includes/taxonomy.php

@@ -709,7 +709,8 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
  *                                 filters and return a `WP_Term` object corresponding to the `$term` data. If `WP_Term`,
  *                                 will return `$term`.
  * @param string     $taxonomy Optional. Taxonomy name that $term is part of.
- * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string     $output   Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                             a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
  * @return array|WP_Term|WP_Error|null Object of the type specified by `$output` on success. When `$output` is 'OBJECT',
  *                                     a WP_Term instance is returned. If taxonomy does not exist, a WP_Error is
@@ -816,9 +817,10 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
  * @param string     $field    Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
  * @param string|int $value    Search for this term value
  * @param string     $taxonomy Taxonomy name. Optional, if `$field` is 'term_taxonomy_id'.
- * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string     $output   Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                             a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT.
  * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
- * @return WP_Term|bool WP_Term instance on success. Will return false if `$taxonomy` does not exist
+ * @return WP_Term|array|false WP_Term instance (or array) on success. Will return false if `$taxonomy` does not exist
  *                             or `$term` was not found.
  */
 function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.7-beta2-39187';
+$wp_version = '4.7-beta2-39188';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/wp-db.php

@@ -2294,10 +2294,8 @@ class wpdb {
 	 * @since 0.71
 	 *
 	 * @param string|null $query  SQL query.
-	 * @param string      $output Optional. one of ARRAY_A | ARRAY_N | OBJECT constants.
+	 * @param string      $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
-	 *                            Return an associative array (column => value, ...),
+	 *                            an stdClass object, an associative array, or a numeric array, respectively. Default OBJECT.
-	 *                            a numerically indexed array (0 => value, ...) or
-	 *                            an object ( ->column = value ), respectively.
 	 * @param int         $y      Optional. Row to return. Indexed from 0.
 	 * @return array|object|null|void Database query result in format specified by $output or null on failure
 	 */