From 0632a3de6833a540ffcdd29ed6617f624f87c0b4 Mon Sep 17 00:00:00 2001
From: Scott Taylor <wonderboymusic@git.wordpress.org>
Date: Sun, 30 Nov 2014 23:23:37 +0000
Subject: [PATCH] Improve various `@param` docs.

See #30224.


git-svn-id: https://develop.svn.wordpress.org/trunk@30674 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/functions.php            | 32 ++++++++++++------------
 src/wp-includes/functions.wp-scripts.php |  2 +-
 src/wp-includes/functions.wp-styles.php  |  4 +--
 src/wp-includes/general-template.php     |  8 +++---
 src/wp-includes/http.php                 |  7 +++---
 src/wp-includes/l10n.php                 |  7 +++++-
 src/wp-includes/media.php                | 14 +++++++++--
 src/wp-includes/meta.php                 |  4 +--
 src/wp-includes/ms-functions.php         |  1 -
 9 files changed, 47 insertions(+), 32 deletions(-)

diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index cbb068e7f7..76013c934e 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -197,7 +197,7 @@ function number_format_i18n( $number, $decimals = 0 ) {
  *
  * @param int|string $bytes    Number of bytes. Note max integer size for integers.
  * @param int        $decimals Optional. Precision of number of decimal places. Default 0.
- * @return bool|string False on failure. Number string on success.
+ * @return string|false False on failure. Number string on success.
  */
 function size_format( $bytes, $decimals = 0 ) {
 	$quant = array(
@@ -641,7 +641,7 @@ function wp_get_http_headers( $url, $deprecated = false ) {
  * @global string $currentday  The day of the current post in the loop.
  * @global string $previousday The day of the previous post in the loop.
  *
- * @return int|bool 1|true when new day, 0|false if not a new day.
+ * @return int 1 when new day, 0 if not a new day.
  */
 function is_new_day() {
 	global $currentday, $previousday;
@@ -842,7 +842,7 @@ function add_magic_quotes( $array ) {
  * @see wp_safe_remote_get()
  *
  * @param string $uri URI/URL of web page to retrieve.
- * @return bool|string HTTP content. False on failure.
+ * @return false|string HTTP content. False on failure.
  */
 function wp_remote_fopen( $uri ) {
 	$parsed_url = @parse_url( $uri );
@@ -1327,9 +1327,9 @@ function is_blog_installed() {
  *
  * @since 2.0.4
  *
- * @param string $actionurl URL to add nonce action.
- * @param string $action    Optional. Nonce action name. Default -1.
- * @param string $name      Optional. Nonce name. Default '_wpnonce'.
+ * @param string     $actionurl URL to add nonce action.
+ * @param int|string $action    Optional. Nonce action name. Default -1.
+ * @param string     $name      Optional. Nonce name. Default '_wpnonce'.
  * @return string Escaped URL with nonce action added.
  */
 function wp_nonce_url( $actionurl, $action = -1, $name = '_wpnonce' ) {
@@ -1357,10 +1357,10 @@ function wp_nonce_url( $actionurl, $action = -1, $name = '_wpnonce' ) {
  *
  * @since 2.0.4
  *
- * @param string $action  Optional. Action name. Default -1.
- * @param string $name    Optional. Nonce name. Default '_wpnonce'.
- * @param bool   $referer Optional. Whether to set the referer field for validation. Default true.
- * @param bool   $echo    Optional. Whether to display or return hidden form field. Default true.
+ * @param int|string $action  Optional. Action name. Default -1.
+ * @param string     $name    Optional. Nonce name. Default '_wpnonce'.
+ * @param bool       $referer Optional. Whether to set the referer field for validation. Default true.
+ * @param bool       $echo    Optional. Whether to display or return hidden form field. Default true.
  * @return string Nonce field HTML markup.
  */
 function wp_nonce_field( $action = -1, $name = "_wpnonce", $referer = true , $echo = true ) {
@@ -1426,7 +1426,7 @@ function wp_original_referer_field( $echo = true, $jump_back_to = 'current' ) {
  *
  * @since 2.0.4
  *
- * @return string|bool False on failure. Referer URL on success.
+ * @return false|string False on failure. Referer URL on success.
  */
 function wp_get_referer() {
 	if ( ! function_exists( 'wp_validate_redirect' ) )
@@ -1447,7 +1447,7 @@ function wp_get_referer() {
  *
  * @since 2.0.4
  *
- * @return string|bool False if no original referer or original referer if set.
+ * @return string|false False if no original referer or original referer if set.
  */
 function wp_get_original_referer() {
 	if ( ! empty( $_REQUEST['_wp_original_http_referer'] ) && function_exists( 'wp_validate_redirect' ) )
@@ -1918,10 +1918,10 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null )
  *
  * @since 2.0.0
  *
- * @param string $name       Filename.
- * @param null   $deprecated Never used. Set to null.
- * @param mixed  $bits       File content
- * @param string $time       Optional. Time formatted in 'yyyy/mm'. Default null.
+ * @param string       $name       Filename.
+ * @param null|string  $deprecated Never used. Set to null.
+ * @param mixed        $bits       File content
+ * @param string       $time       Optional. Time formatted in 'yyyy/mm'. Default null.
  * @return array
  */
 function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
diff --git a/src/wp-includes/functions.wp-scripts.php b/src/wp-includes/functions.wp-scripts.php
index 8c3151c45e..6eb7a44f89 100644
--- a/src/wp-includes/functions.wp-scripts.php
+++ b/src/wp-includes/functions.wp-scripts.php
@@ -21,7 +21,7 @@
  *
  * @since 2.6.0
  *
- * @param array|bool $handles Optional. Scripts to be printed. Default 'false'.
+ * @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'.
  * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
  */
 function wp_print_scripts( $handles = false ) {
diff --git a/src/wp-includes/functions.wp-styles.php b/src/wp-includes/functions.wp-styles.php
index 83db482cc0..ead62965eb 100644
--- a/src/wp-includes/functions.wp-styles.php
+++ b/src/wp-includes/functions.wp-styles.php
@@ -19,7 +19,7 @@
  *
  * @since 2.6.0
  *
- * @param array|bool $handles Styles to be printed. Default 'false'.
+ * @param string|bool|array $handles Styles to be printed. Default 'false'.
  * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
  */
 function wp_print_styles( $handles = false ) {
@@ -236,7 +236,7 @@ function wp_style_is( $handle, $list = 'enqueued' ) {
  * @param string $handle Name of the stylesheet.
  * @param string $key    Name of data point for which we're storing a value.
  *                       Accepts 'conditional', 'rtl' and 'suffix', 'alt' and 'title'.
- * @param mixed  $data   String containing the CSS data to be added.
+ * @param mixed  $value  String containing the CSS data to be added.
  * @return bool True on success, false on failure.
  */
 function wp_style_add_data( $handle, $key, $value ) {
diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index 5eeb11a018..034135d09a 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -1858,7 +1858,7 @@ function the_date( $d = '', $before = '', $after = '', $echo = true ) {
  *
  * @param  string      $d    Optional. PHP date format defaults to the date_format option if not specified.
  * @param  int|WP_Post $post Optional. Post ID or WP_Post object. Default current post.
- * @return string|bool Date the current post was written. False on failure.
+ * @return false|string Date the current post was written. False on failure.
  */
 function get_the_date( $d = '', $post = null ) {
 	$post = get_post( $post );
@@ -1976,7 +1976,7 @@ function the_time( $d = '' ) {
  *                          was written. Either 'G', 'U', or php date format defaults
  *                          to the value specified in the time_format option. Default empty.
  * @param int|WP_Post $post WP_Post object or ID. Default is global $post object.
- * @return string|int|bool Formatted date string or Unix timestamp. False on failure.
+ * @return false|string Formatted date string or Unix timestamp. False on failure.
  */
 function get_the_time( $d = '', $post = null ) {
 	$post = get_post($post);
@@ -2014,7 +2014,7 @@ function get_the_time( $d = '', $post = null ) {
  * @param bool        $gmt       Optional. Whether to retrieve the GMT time. Default false.
  * @param int|WP_Post $post      WP_Post object or ID. Default is global $post object.
  * @param bool        $translate Whether to translate the time string. Default false.
- * @return string|int|bool Formatted date string or Unix timestamp. False on failure.
+ * @return false|string Formatted date string or Unix timestamp. False on failure.
  */
 function get_post_time( $d = 'U', $gmt = false, $post = null, $translate = false ) {
 	$post = get_post($post);
@@ -2101,7 +2101,7 @@ function get_the_modified_time($d = '') {
  * @param bool        $gmt       Optional. Whether to retrieve the GMT time. Default false.
  * @param int|WP_Post $post      WP_Post object or ID. Default is global $post object.
  * @param bool        $translate Whether to translate the time string. Default false.
- * @return string|int|bool Formatted date string or Unix timestamp. False on failure.
+ * @return false|string Formatted date string or Unix timestamp. False on failure.
  */
 function get_post_modified_time( $d = 'U', $gmt = false, $post = null, $translate = false ) {
 	$post = get_post($post);
diff --git a/src/wp-includes/http.php b/src/wp-includes/http.php
index 8519d1834d..02b653f5a4 100644
--- a/src/wp-includes/http.php
+++ b/src/wp-includes/http.php
@@ -381,8 +381,8 @@ function get_allowed_http_origins() {
  *
  * @since 3.4.0
  *
- * @param string Origin URL. If not provided, the value of get_http_origin() is used.
- * @return bool True if the origin is allowed. False otherwise.
+ * @param null|string $origin Origin URL. If not provided, the value of get_http_origin() is used.
+ * @return bool|null True if the origin is allowed. False otherwise.
  */
 function is_allowed_http_origin( $origin = null ) {
 	$origin_arg = $origin;
@@ -441,7 +441,8 @@ function send_origin_headers() {
  *
  * @since 3.5.2
  *
- * @return mixed URL or false on failure.
+ * @param string $url
+ * @return false|string URL or false on failure.
  */
 function wp_http_validate_url( $url ) {
 	$original_url = $url;
diff --git a/src/wp-includes/l10n.php b/src/wp-includes/l10n.php
index 8d4fedefd7..67215452b7 100644
--- a/src/wp-includes/l10n.php
+++ b/src/wp-includes/l10n.php
@@ -389,6 +389,11 @@ function _n_noop( $singular, $plural, $domain = null ) {
  * Register plural strings with context in POT file, but don't translate them.
  *
  * @since 2.8.0
+ * @param string $singular
+ * @param string $plural
+ * @param string $context
+ * @param string|null $domain
+ * @return array
  */
 function _nx_noop( $singular, $plural, $context, $domain = null ) {
 	return array( 0 => $singular, 1 => $plural, 2 => $context, 'singular' => $singular, 'plural' => $plural, 'context' => $context, 'domain' => $domain );
@@ -700,7 +705,7 @@ function load_child_theme_textdomain( $domain, $path = false ) {
  * @since 2.8.0
  *
  * @param string $domain Text domain. Unique identifier for retrieving translated strings.
- * @return Translations A Translations instance.
+ * @return NOOP_Translations A Translations instance.
  */
 function get_translations_for_domain( $domain ) {
 	global $l10n;
diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
index d1735249ab..c7d092d966 100644
--- a/src/wp-includes/media.php
+++ b/src/wp-includes/media.php
@@ -2037,7 +2037,7 @@ function get_taxonomies_for_attachments( $output = 'names' ) {
  *
  * @param int $width Image width
  * @param int $height Image height
- * @return image resource
+ * @return resource resource
  */
 function wp_imagecreatetruecolor($width, $height) {
 	$img = imagecreatetruecolor($width, $height);
@@ -2053,6 +2053,12 @@ function wp_imagecreatetruecolor($width, $height) {
  *
  * @since 2.9.0
  * @see WP_Embed::register_handler()
+ *
+ * @global WP_Embed $wp_embed
+ * @param string   $id
+ * @param string   $regex
+ * @param callable $callback
+ * @param int      $priority
  */
 function wp_embed_register_handler( $id, $regex, $callback, $priority = 10 ) {
 	global $wp_embed;
@@ -2064,6 +2070,10 @@ function wp_embed_register_handler( $id, $regex, $callback, $priority = 10 ) {
  *
  * @since 2.9.0
  * @see WP_Embed::unregister_handler()
+ *
+ * @global WP_Embed $wp_embed
+ * @param string $id
+ * @param int    $priority
  */
 function wp_embed_unregister_handler( $id, $priority = 10 ) {
 	global $wp_embed;
@@ -2135,7 +2145,7 @@ function wp_expand_dimensions( $example_width, $example_height, $max_width, $max
  *
  * @param string $url The URL that should be embedded.
  * @param array $args Additional arguments and parameters.
- * @return bool|string False on failure or the embed HTML on success.
+ * @return false|string False on failure or the embed HTML on success.
  */
 function wp_oembed_get( $url, $args = '' ) {
 	require_once( ABSPATH . WPINC . '/class-oembed.php' );
diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php
index 9002c46782..dbf07a54e4 100644
--- a/src/wp-includes/meta.php
+++ b/src/wp-includes/meta.php
@@ -1539,7 +1539,8 @@ function _get_meta_table($type) {
  *
  * @since 3.1.3
  *
- * @param string $meta_key Meta key
+ * @param string      $meta_key Meta key
+ * @param string|null $meta_type
  * @return bool True if the key is protected, false otherwise.
  */
 function is_protected_meta( $meta_key, $meta_type = null ) {
@@ -1595,7 +1596,6 @@ function sanitize_meta( $meta_key, $meta_value, $meta_type ) {
  * @param string $meta_key Meta key
  * @param string|array $sanitize_callback A function or method to call when sanitizing the value of $meta_key.
  * @param string|array $auth_callback Optional. A function or method to call when performing edit_post_meta, add_post_meta, and delete_post_meta capability checks.
- * @param array $args Arguments
  */
 function register_meta( $meta_type, $meta_key, $sanitize_callback, $auth_callback = null ) {
 	if ( is_callable( $sanitize_callback ) )
diff --git a/src/wp-includes/ms-functions.php b/src/wp-includes/ms-functions.php
index 04f4294de8..2b6c55594c 100644
--- a/src/wp-includes/ms-functions.php
+++ b/src/wp-includes/ms-functions.php
@@ -2024,7 +2024,6 @@ function is_user_spammy( $user = null ) {
  *
  * @param int $old_value
  * @param int $value The new public value
- * @return bool
  */
 function update_blog_public( $old_value, $value ) {
 	update_blog_status( get_current_blog_id(), 'public', (int) $value );