Docs: Document default values for optional parameters in various DocBlocks.

Props paulkevan, costdev, audrasjb, SergeyBiryukov.
See #56792.

git-svn-id: https://develop.svn.wordpress.org/trunk@55398 602fd350-edb4-49c9-b593-d223f7449a82

Author: SergeyBiryukov

src/wp-includes/author-template.php

@@ -155,7 +155,7 @@ function the_modified_author() {
  * @global WP_User $authordata The current author's data.
  *
  * @param string    $field   Optional. The user field to retrieve. Default empty.
- * @param int|false $user_id Optional. User ID.
+ * @param int|false $user_id Optional. User ID. Defaults to the current post author.
  * @return string The author's field from the current author's DB object, otherwise an empty string.
  */
 function get_the_author_meta( $field = '', $user_id = false ) {
@@ -196,7 +196,7 @@ function get_the_author_meta( $field = '', $user_id = false ) {
  *
  * @param string    $field   Selects the field of the users record. See get_the_author_meta()
  *                           for the list of possible fields.
- * @param int|false $user_id Optional. User ID.
+ * @param int|false $user_id Optional. User ID. Defaults to the current post author.
  *
  * @see get_the_author_meta()
  */

src/wp-includes/bookmark.php

@@ -71,7 +71,7 @@ function get_bookmark( $bookmark, $output = OBJECT, $filter = 'raw' ) {
  *
  * @param string $field    The name of the data field to return.
  * @param int    $bookmark The bookmark ID to get field.
- * @param string $context  Optional. The context of how the field will be used.
+ * @param string $context  Optional. The context of how the field will be used. Default 'display'.
  * @return string|WP_Error
  */
 function get_bookmark_field( $field, $bookmark, $context = 'display' ) {

src/wp-includes/class-wp-editor.php

@@ -1451,7 +1451,7 @@ private static function get_translation() {
 	 *
 	 * @param string $mce_locale The locale used for the editor.
 	 * @param bool   $json_only  Optional. Whether to include the JavaScript calls to tinymce.addI18n() and
-	 *                           tinymce.ScriptLoader.markDone().
+	 *                           tinymce.ScriptLoader.markDone(). Default false.
 	 * @return string Translation object, JSON encoded.
 	 */
 	public static function wp_mce_translation( $mce_locale = '', $json_only = false ) {
@@ -1751,7 +1751,12 @@ public static function wp_fullscreen_html() {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param array $args Optional. Accepts 'pagenum' and 's' (search) arguments.
+	 * @param array $args {
+	 *     Optional. Array of link query arguments.
+	 *
+	 *     @type int    $pagenum Page number. Default 1.
+	 *     @type string $s       Search keywords.
+	 * }
 	 * @return array|false $results {
 	 *     An array of associative arrays of query results, false if there are none.
 	 *

src/wp-includes/class-wp-error.php

@@ -56,7 +56,7 @@ class WP_Error {
 	 *
 	 * @param string|int $code    Error code.
 	 * @param string     $message Error message.
-	 * @param mixed      $data    Optional. Error data.
+	 * @param mixed      $data    Optional. Error data. Default empty string.
 	 */
 	public function __construct( $code = '', $message = '', $data = '' ) {
 		if ( empty( $code ) ) {
@@ -103,7 +103,8 @@ public function get_error_code() {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @param string|int $code Optional. Retrieve messages matching code, if exists.
+	 * @param string|int $code Optional. Error code to retrieve the messages for.
+	 *                         Default empty string.
 	 * @return string[] Error strings on success, or empty array if there are none.
 	 */
 	public function get_error_messages( $code = '' ) {
@@ -132,7 +133,8 @@ public function get_error_messages( $code = '' ) {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @param string|int $code Optional. Error code to retrieve message.
+	 * @param string|int $code Optional. Error code to retrieve the message for.
+	 *                         Default empty string.
 	 * @return string The error message.
 	 */
 	public function get_error_message( $code = '' ) {
@@ -151,7 +153,7 @@ public function get_error_message( $code = '' ) {
 	 *
 	 * @since 2.1.0
 	 *
-	 * @param string|int $code Optional. Error code.
+	 * @param string|int $code Optional. Error code. Default empty string.
 	 * @return mixed Error data, if it exists.
 	 */
 	public function get_error_data( $code = '' ) {
@@ -185,7 +187,7 @@ public function has_errors() {
 	 *
 	 * @param string|int $code    Error code.
 	 * @param string     $message Error message.
-	 * @param mixed      $data    Optional. Error data.
+	 * @param mixed      $data    Optional. Error data. Default empty string.
 	 */
 	public function add( $code, $message, $data = '' ) {
 		$this->errors[ $code ][] = $message;

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

@@ -345,6 +345,7 @@ public function get_cast_for_type( $type = '' ) {
 	 * @param string $primary_id_column ID column for the filtered object in $primary_table.
 	 * @param object $context           Optional. The main query object that corresponds to the type, for
 	 *                                  example a `WP_Query`, `WP_User_Query`, or `WP_Site_Query`.
+	 *                                  Default null.
 	 * @return string[]|false {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query,
 	 *     or false if no table exists for the requested meta type.
@@ -521,6 +522,7 @@ protected function get_sql_for_query( &$query, $depth = 0 ) {
 	 * @param array  $parent_query Parent query array.
 	 * @param string $clause_key   Optional. The array key used to name the clause in the original `$meta_query`
 	 *                             parameters. If not provided, a key will be generated automatically.
+	 *                             Default empty string.
 	 * @return string[] {
 	 *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
 	 *

src/wp-includes/class-wp-widget.php

@@ -152,7 +152,7 @@ public function form( $instance ) {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param string $id_base         Optional. Base ID for the widget, lowercase and unique. If left empty,
+	 * @param string $id_base         Base ID for the widget, lowercase and unique. If left empty,
 	 *                                a portion of the widget's PHP class name will be used. Has to be unique.
 	 * @param string $name            Name for the widget displayed on the configuration page.
 	 * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for
@@ -188,7 +188,7 @@ public function __construct( $id_base, $name, $widget_options = array(), $contro
 	 *
 	 * @see WP_Widget::__construct()
 	 *
-	 * @param string $id_base         Optional. Base ID for the widget, lowercase and unique. If left empty,
+	 * @param string $id_base         Base ID for the widget, lowercase and unique. If left empty,
 	 *                                a portion of the widget's PHP class name will be used. Has to be unique.
 	 * @param string $name            Name for the widget displayed on the configuration page.
 	 * @param array  $widget_options  Optional. Widget options. See wp_register_sidebar_widget() for

src/wp-includes/class-wpdb.php

@@ -1072,7 +1072,7 @@ public function set_prefix( $prefix, $set_table_names = true ) {
 	 * @since 3.0.0
 	 *
 	 * @param int $blog_id
-	 * @param int $network_id Optional.
+	 * @param int $network_id Optional. Network ID. Default 0.
 	 * @return int Previous blog ID.
 	 */
 	public function set_blog_id( $blog_id, $network_id = 0 ) {
@@ -1101,7 +1101,8 @@ public function set_blog_id( $blog_id, $network_id = 0 ) {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param int $blog_id Optional.
+	 * @param int $blog_id Optional. Blog ID to retrieve the table prefix for.
+	 *                     Defaults to the current blog ID.
 	 * @return string Blog prefix.
 	 */
 	public function get_blog_prefix( $blog_id = null ) {
@@ -1220,7 +1221,8 @@ public function tables( $scope = 'all', $prefix = true, $blog_id = 0 ) {
 	 * @since 0.71
 	 *
 	 * @param string          $db  Database name.
-	 * @param mysqli|resource $dbh Optional database connection.
+	 * @param mysqli|resource $dbh Optional. Database connection.
+	 *                             Defaults to the current database handle.
 	 */
 	public function select( $db, $dbh = null ) {
 		if ( is_null( $dbh ) ) {
@@ -2561,7 +2563,7 @@ public function remove_placeholder_escape( $query ) {
 	 *                             If string, that format will be used for all of the values in $data.
 	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
 	 *                             If omitted, all values in $data will be treated as strings unless otherwise
-	 *                             specified in wpdb::$field_types.
+	 *                             specified in wpdb::$field_types. Default null.
 	 * @return int|false The number of rows inserted, or false on error.
 	 */
 	public function insert( $table, $data, $format = null ) {
@@ -2591,7 +2593,7 @@ public function insert( $table, $data, $format = null ) {
 	 *                             If string, that format will be used for all of the values in $data.
 	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
 	 *                             If omitted, all values in $data will be treated as strings unless otherwise
-	 *                             specified in wpdb::$field_types.
+	 *                             specified in wpdb::$field_types. Default null.
 	 * @return int|false The number of rows affected, or false on error.
 	 */
 	public function replace( $table, $data, $format = null ) {
@@ -2618,7 +2620,7 @@ public function replace( $table, $data, $format = null ) {
 	 *                             If string, that format will be used for all of the values in $data.
 	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
 	 *                             If omitted, all values in $data will be treated as strings unless otherwise
-	 *                             specified in wpdb::$field_types.
+	 *                             specified in wpdb::$field_types. Default null.
 	 * @param string       $type   Optional. Type of operation. Possible values include 'INSERT' or 'REPLACE'.
 	 *                             Default 'INSERT'.
 	 * @return int|false The number of rows affected, or false on error.
@@ -2684,11 +2686,11 @@ public function _insert_replace_helper( $table, $data, $format = null, $type = '
 	 *                                   If string, that format will be used for all of the values in $data.
 	 *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
 	 *                                   If omitted, all values in $data will be treated as strings unless otherwise
-	 *                                   specified in wpdb::$field_types.
+	 *                                   specified in wpdb::$field_types. Default null.
 	 * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
 	 *                                   If string, that format will be used for all of the items in $where.
 	 *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
-	 *                                   If omitted, all values in $where will be treated as strings.
+	 *                                   If omitted, all values in $where will be treated as strings. Default null.
 	 * @return int|false The number of rows updated, or false on error.
 	 */
 	public function update( $table, $data, $where, $format = null, $where_format = null ) {
@@ -2760,7 +2762,7 @@ public function update( $table, $data, $where, $format = null, $where_format = n
 	 *                                   If string, that format will be used for all of the items in $where.
 	 *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
 	 *                                   If omitted, all values in $data will be treated as strings unless otherwise
-	 *                                   specified in wpdb::$field_types.
+	 *                                   specified in wpdb::$field_types. Default null.
 	 * @return int|false The number of rows deleted, or false on error.
 	 */
 	public function delete( $table, $where, $where_format = null ) {
@@ -2967,8 +2969,8 @@ protected function process_field_lengths( $data, $table ) {
 	 * @since 0.71
 	 *
 	 * @param string|null $query Optional. SQL query. Defaults to null, use the result from the previous query.
-	 * @param int         $x     Optional. Column of value to return. Indexed from 0.
-	 * @param int         $y     Optional. Row of value to return. Indexed from 0.
+	 * @param int         $x     Optional. Column of value to return. Indexed from 0. Default 0.
+	 * @param int         $y     Optional. Row of value to return. Indexed from 0. Default 0.
 	 * @return string|null Database query result (as string), or null on failure.
 	 */
 	public function get_var( $query = null, $x = 0, $y = 0 ) {
@@ -3002,7 +3004,7 @@ public function get_var( $query = null, $x = 0, $y = 0 ) {
 	 * @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 int         $y      Optional. Row to return. Indexed from 0.
+	 * @param int         $y      Optional. Row to return. Indexed from 0. Default 0.
 	 * @return array|object|null|void Database query result in format specified by $output or null on failure.
 	 */
 	public function get_row( $query = null, $output = OBJECT, $y = 0 ) {
@@ -3046,7 +3048,7 @@ public function get_row( $query = null, $output = OBJECT, $y = 0 ) {
 	 * @since 0.71
 	 *
 	 * @param string|null $query Optional. SQL query. Defaults to previous query.
-	 * @param int         $x     Optional. Column to return. Indexed from 0.
+	 * @param int         $x     Optional. Column to return. Indexed from 0. Default 0.
 	 * @return array Database query result. Array indexed from 0 by SQL result row number.
 	 */
 	public function get_col( $query = null, $x = 0 ) {
@@ -3083,6 +3085,7 @@ public function get_col( $query = null, $x = 0 ) {
 	 *                       or an object ( ->column = value ), respectively. With OBJECT_K,
 	 *                       return an associative array of row objects keyed by the value
 	 *                       of each row's first column's value. Duplicate keys are discarded.
+	 *                       Default OBJECT.
 	 * @return array|object|null Database query results.
 	 */
 	public function get_results( $query = null, $output = OBJECT ) {

src/wp-includes/comment-template.php

@@ -2159,7 +2159,7 @@ function _get_comment_reply_id( $post = null ) {
  *     @type bool     $short_ping        Whether to output short pings. Default false.
  *     @type bool     $echo              Whether to echo the output or return it. Default true.
  * }
- * @param WP_Comment[] $comments Optional. Array of WP_Comment objects.
+ * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. Default null.
  * @return void|string Void if 'echo' argument is true, or no comments to list.
  *                     Otherwise, HTML list of comments.
  */

src/wp-includes/comment.php

@@ -155,7 +155,13 @@ function check_comment( $author, $email, $url, $comment, $user_ip, $user_agent,
  * @since 4.1.0 Refactored to leverage WP_Comment_Query over a direct query.
  *
  * @param int   $post_id The ID of the post.
- * @param array $args    Optional. See WP_Comment_Query::__construct() for information on accepted arguments.
+ * @param array $args    {
+ *     Optional. See WP_Comment_Query::__construct() for information on accepted arguments.
+ *
+ *     @type int    $status  Comment status to limit results by. Defaults to approved comments.
+ *     @type int    $post_id Limit results to those affiliated with a given post ID.
+ *     @type string $order   How to order retrieved comments. Default 'ASC'.
+ * }
  * @return WP_Comment[]|int[]|int The approved comments, or number of comments if `$count`
  *                                argument is true.
  */
@@ -236,7 +242,7 @@ function get_comment( $comment = null, $output = OBJECT ) {
  * @since 2.7.0
  *
  * @param string|array $args Optional. Array or string of arguments. See WP_Comment_Query::__construct()
- *                           for information on accepted arguments. Default empty.
+ *                           for information on accepted arguments. Default empty string.
  * @return WP_Comment[]|int[]|int List of comments or number of found comments if `$count` argument is true.
  */
 function get_comments( $args = '' ) {
@@ -449,7 +455,7 @@ function add_comment_meta( $comment_id, $meta_key, $meta_value, $unique = false
  * @param string $meta_key   Metadata name.
  * @param mixed  $meta_value Optional. Metadata value. If provided,
  *                           rows will only be removed that match the value.
- *                           Must be serializable if non-scalar. Default empty.
+ *                           Must be serializable if non-scalar. Default empty string.
  * @return bool True on success, false on failure.
  */
 function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) {
@@ -465,7 +471,7 @@ function delete_comment_meta( $comment_id, $meta_key, $meta_value = '' ) {
  *
  * @param int    $comment_id Comment ID.
  * @param string $key        Optional. The meta key to retrieve. By default,
- *                           returns data for all keys.
+ *                           returns data for all keys. Default empty string.
  * @param bool   $single     Optional. Whether to return a single value.
  *                           This parameter has no effect if `$key` is not specified.
  *                           Default false.
@@ -495,7 +501,7 @@ function get_comment_meta( $comment_id, $key = '', $single = false ) {
  * @param mixed  $meta_value Metadata value. Must be serializable if non-scalar.
  * @param mixed  $prev_value Optional. Previous value to check before updating.
  *                           If specified, only update existing metadata entries with
- *                           this value. Otherwise, update all entries. Default empty.
+ *                           this value. Otherwise, update all entries. Default empty string.
  * @return int|bool Meta ID if the key didn't exist, true on successful update,
  *                  false on failure or if the value passed to the function
  *                  is the same as the one that is already in the database.
@@ -985,8 +991,10 @@ function separate_comments( &$comments ) {
  * @global WP_Query $wp_query WordPress Query object.
  *
  * @param WP_Comment[] $comments Optional. Array of WP_Comment objects. Defaults to `$wp_query->comments`.
- * @param int          $per_page Optional. Comments per page.
- * @param bool         $threaded Optional. Control over flat or threaded comments.
+ * @param int          $per_page Optional. Comments per page. Defaults to the value of `comments_per_page`
+ *                               query var, option of the same name, or 1 (in that order).
+ * @param bool         $threaded Optional. Control over flat or threaded comments. Defaults to the value
+ *                               of `thread_comments` option.
  * @return int Number of comment pages.
  */
 function get_comment_pages_count( $comments = null, $per_page = null, $threaded = null ) {