Add doc blocks to functions that are missing them.

If the function has no need for `@param` or `@return`, do an archeaological dig to find `@since`.

See #32444.

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


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

wp-admin/includes/comment.php

@@ -167,6 +167,9 @@ function floated_admin_avatar( $name ) {
 	return "$avatar $name";
 }
 
+/**
+ * @since 2.7.0
+ */
 function enqueue_comment_hotkeys_js() {
 	if ( 'true' == get_user_option( 'comment_shortcuts' ) )
 		wp_enqueue_script( 'jquery-table-hotkeys' );

wp-admin/includes/dashboard.php

@@ -355,6 +355,9 @@ function wp_dashboard_right_now() {
 	<?php endif;
 }
 
+/**
+ * @since 3.1.0
+ */
 function wp_network_dashboard_right_now() {
 	$actions = array();
 	if ( current_user_can('create_sites') )
@@ -1247,6 +1250,12 @@ function wp_dashboard_browser_nag() {
 	echo apply_filters( 'browse-happy-notice', $notice, $response );
 }
 
+/**
+ * @since 3.2.0
+ *
+ * @param array $classes
+ * @return array
+ */
 function dashboard_browser_nag_class( $classes ) {
 	$response = wp_check_browser_version();
 

wp-admin/includes/media.php

@@ -1574,6 +1574,13 @@ function get_media_item( $attachment_id, $args = null ) {
 	return $item;
 }
 
+/**
+ * @since 3.5.0
+ *
+ * @param int   $attachment_id
+ * @param array $args
+ * @return array
+ */
 function get_compat_media_markup( $attachment_id, $args = null ) {
 	$post = get_post( $attachment_id );
 

wp-admin/includes/misc.php

@@ -310,6 +310,12 @@ function show_message($message) {
 	flush();
 }
 
+/**
+ * @since 2.8.0
+ *
+ * @param string $content
+ * @return array
+ */
 function wp_doc_link_parse( $content ) {
 	if ( !is_string( $content ) || empty( $content ) )
 		return array();
@@ -676,6 +682,9 @@ function wp_color_scheme_settings() {
 	echo '<script type="text/javascript">var _wpColorScheme = ' . wp_json_encode( array( 'icons' => $icon_colors ) ) . ";</script>\n";
 }
 
+/**
+ * @since 3.3.0
+ */
 function _ipad_meta() {
 	if ( wp_is_mobile() ) {
 		?>

wp-admin/includes/ms-deprecated.php

@@ -64,14 +64,25 @@ function is_wpmu_sitewide_plugin( $file ) {
 	return is_network_only_plugin( $file );
 }
 
+/**
+ * @deprecated 3.4.0
+ * @see WP_Theme::get_allowed_on_network()
+ */
 function get_site_allowed_themes() {
 	_deprecated_function( __FUNCTION__, '3.4', 'WP_Theme::get_allowed_on_network()' );
 	return array_map( 'intval', WP_Theme::get_allowed_on_network() );
 }
 
+/**
+ * @deprecated 3.4.0
+ * @see WP_Theme::get_allowed_on_site()
+ */
 function wpmu_get_blog_allowedthemes( $blog_id = 0 ) {
 	_deprecated_function( __FUNCTION__, '3.4', 'WP_Theme::get_allowed_on_site()' );
 	return array_map( 'intval', WP_Theme::get_allowed_on_site( $blog_id ) );
 }
 
+/**
+ * @deprecated
+ */
 function ms_deprecated_blogs_file() {}

wp-admin/includes/plugin-install.php

@@ -130,6 +130,9 @@ function install_popular_tags( $args = array() ) {
 	return $tags;
 }
 
+/**
+ * @since 2.7.0
+ */
 function install_dashboard() {
 	?>
 	<p><?php printf( __( 'Plugins extend and expand the functionality of WordPress. You may automatically install plugins from the <a href="%1$s">WordPress Plugin Directory</a> or upload a plugin in .zip format via <a href="%2$s">this page</a>.' ), 'https://wordpress.org/plugins/', self_admin_url( 'plugin-install.php?tab=upload' ) ); ?></p>

wp-admin/includes/plugin.php

@@ -1658,6 +1658,13 @@ function get_admin_page_title() {
 	return $title;
 }
 
+/**
+ * @since 2.3.0
+ *
+ * @param string $plugin_page
+ * @param string $parent_page
+ * @return string|null
+ */
 function get_plugin_page_hook( $plugin_page, $parent_page ) {
 	$hook = get_plugin_page_hookname( $plugin_page, $parent_page );
 	if ( has_action($hook) )

wp-admin/includes/theme-install.php

@@ -135,6 +135,9 @@ function install_themes_dashboard() {
 <?php
 }
 
+/**
+ * @since 2.8.0
+ */
 function install_themes_upload() {
 ?>
 <p class="install-help"><?php _e('If you have a theme in a .zip format, you may install it by uploading it here.'); ?></p>

wp-admin/includes/update.php

@@ -259,6 +259,11 @@ function update_right_now_message() {
 	echo "<p id='wp-version-message'>$msg</p>";
 }
 
+/**
+ * @since 2.9.0
+ *
+ * @return array
+ */
 function get_plugin_updates() {
 	$all_plugins = get_plugins();
 	$upgrade_plugins = array();
@@ -273,6 +278,9 @@ function get_plugin_updates() {
 	return $upgrade_plugins;
 }
 
+/**
+ * @since 2.9.0
+ */
 function wp_plugin_update_rows() {
 	if ( !current_user_can('update_plugins' ) )
 		return;
@@ -377,6 +385,9 @@ function get_theme_updates() {
 	return $update_themes;
 }
 
+/**
+ * @since 3.1.0
+ */
 function wp_theme_update_rows() {
 	if ( !current_user_can('update_themes' ) )
 		return;

wp-admin/update-core.php

@@ -114,6 +114,9 @@ function list_core_update( $update ) {
 
 }
 
+/**
+ * @since 2.7.0
+ */
 function dismissed_updates() {
 	$dismissed = get_core_updates( array( 'dismissed' => true, 'available' => false ) );
 	if ( $dismissed ) {
@@ -305,6 +308,9 @@ function list_plugin_updates() {
 <?php
 }
 
+/**
+ * @since 2.9.0
+ */
 function list_theme_updates() {
 	$themes = get_theme_updates();
 	if ( empty( $themes ) ) {
@@ -353,6 +359,9 @@ function list_theme_updates() {
 <?php
 }
 
+/**
+ * @since 3.7.0
+ */
 function list_translation_updates() {
 	$updates = wp_get_translation_updates();
 	if ( ! $updates ) {
@@ -457,6 +466,9 @@ function do_core_upgrade( $reinstall = false ) {
 	<?php
 }
 
+/**
+ * @since 2.7.0
+ */
 function do_dismiss_core_update() {
 	$version = isset( $_POST['version'] )? $_POST['version'] : false;
 	$locale = isset( $_POST['locale'] )? $_POST['locale'] : 'en_US';
@@ -468,6 +480,9 @@ function do_dismiss_core_update() {
 	exit;
 }
 
+/**
+ * @since 2.7.0
+ */
 function do_undismiss_core_update() {
 	$version = isset( $_POST['version'] )? $_POST['version'] : false;
 	$locale = isset( $_POST['locale'] )? $_POST['locale'] : 'en_US';

wp-includes/compat.php

@@ -195,6 +195,12 @@ if ( !function_exists('json_encode') ) {
 }
 
 if ( !function_exists('json_decode') ) {
+	/**
+	 * @global Services_JSON $wp_json
+	 * @param string $string
+	 * @param bool   $assoc_array
+	 * @return object|array
+	 */
 	function json_decode( $string, $assoc_array = false ) {
 		global $wp_json;
 
@@ -208,6 +214,11 @@ if ( !function_exists('json_decode') ) {
 			$res = _json_decode_object_helper( $res );
 		return $res;
 	}
+
+	/**
+	 * @param object $data
+	 * @return array
+	 */
 	function _json_decode_object_helper($data) {
 		if ( is_object($data) )
 			$data = get_object_vars($data);

wp-includes/locale.php

@@ -191,6 +191,9 @@ class WP_Locale {
 		}
 	}
 
+	/**
+	 * @since 3.8.0
+	 */
 	function rtl_src_admin_notice() {
 		echo '<div class="error"><p>' . 'The <code>build</code> directory of the develop repository must be used for RTL.' . '</p></div>';
 	}

wp-includes/pomo/entry.php

@@ -66,6 +66,9 @@ class Translation_Entry {
 		return is_null($this->context)? $this->singular : $this->context.chr(4).$this->singular;
 	}
 
+	/**
+	 * @param object $other
+	 */
 	function merge_with(&$other) {
 		$this->flags = array_unique( array_merge( $this->flags, $other->flags ) );
 		$this->references = array_unique( array_merge( $this->references, $other->references ) );

wp-includes/pomo/mo.php

@@ -27,6 +27,10 @@ class MO extends Gettext_Translations {
 		return $this->import_from_reader($reader);
 	}
 
+	/**
+	 * @param string $filename
+	 * @return bool
+	 */
 	function export_to_file($filename) {
 		$fh = fopen($filename, 'wb');
 		if ( !$fh ) return false;
@@ -35,6 +39,9 @@ class MO extends Gettext_Translations {
 		return $res;
 	}
 
+	/**
+	 * @return string|false
+	 */
 	function export() {
 		$tmp_fh = fopen("php://temp", 'r+');
 		if ( !$tmp_fh ) return false;
@@ -43,6 +50,10 @@ class MO extends Gettext_Translations {
 		return stream_get_contents( $tmp_fh );
 	}
 
+	/**
+	 * @param Translation_Entry $entry
+	 * @return bool
+	 */
 	function is_entry_good_for_export( $entry ) {
 		if ( empty( $entry->translations ) ) {
 			return false;
@@ -55,6 +66,10 @@ class MO extends Gettext_Translations {
 		return true;
 	}
 
+	/**
+	 * @param resource $fh
+	 * @return true
+	 */
 	function export_to_file_handle($fh) {
 		$entries = array_filter( $this->entries, array( $this, 'is_entry_good_for_export' ) );
 		ksort($entries);
@@ -101,6 +116,10 @@ class MO extends Gettext_Translations {
 		return true;
 	}
 
+	/**
+	 * @param Translation_Entry $entry
+	 * @return string
+	 */
 	function export_original($entry) {
 		//TODO: warnings for control characters
 		$exported = $entry->singular;
@@ -109,11 +128,18 @@ class MO extends Gettext_Translations {
 		return $exported;
 	}
 
+	/**
+	 * @param Translation_Entry $entry
+	 * @return string
+	 */
 	function export_translations($entry) {
 		//TODO: warnings for control characters
 		return implode(chr(0), $entry->translations);
 	}
 
+	/**
+	 * @return string
+	 */
 	function export_headers() {
 		$exported = '';
 		foreach($this->headers as $header => $value) {
@@ -122,6 +148,10 @@ class MO extends Gettext_Translations {
 		return $exported;
 	}
 
+	/**
+	 * @param int $magic
+	 * @return string|false
+	 */
 	function get_byteorder($magic) {
 		// The magic is 0x950412de
 
@@ -254,10 +284,17 @@ class MO extends Gettext_Translations {
 		return $entry;
 	}
 
+	/**
+	 * @param int $count
+	 * @return string
+	 */
 	function select_plural_form($count) {
 		return $this->gettext_select_plural_form($count);
 	}
 
+	/**
+	 * @return int
+	 */
 	function get_plural_forms_count() {
 		return $this->_nplurals;
 	}

wp-includes/pomo/streams.php

@@ -101,15 +101,23 @@ class POMO_Reader {
 		}
 	}
 
-
+	/**
+	 * @return int
+	 */
 	function pos() {
 		return $this->_pos;
 	}
 
+	/**
+	 * @return true
+	 */
 	function is_resource() {
 		return true;
 	}
 
+	/**
+	 * @return true
+	 */
 	function close() {
 		return true;
 	}
@@ -146,18 +154,30 @@ class POMO_FileReader extends POMO_Reader {
 		return true;
 	}
 
+	/**
+	 * @return bool
+	 */
 	function is_resource() {
 		return is_resource($this->_f);
 	}
 
+	/**
+	 * @return bool
+	 */
 	function feof() {
 		return feof($this->_f);
 	}
 
+	/**
+	 * @return bool
+	 */
 	function close() {
 		return fclose($this->_f);
 	}
 
+	/**
+	 * @return string
+	 */
 	function read_all() {
 		$all = '';
 		while ( !$this->feof() )
@@ -203,10 +223,16 @@ class POMO_StringReader extends POMO_Reader {
 		return $this->_pos;
 	}
 
+	/**
+	 * @return int
+	 */
 	function length() {
 		return $this->strlen($this->_str);
 	}
 
+	/**
+	 * @return string
+	 */
 	function read_all() {
 		return $this->substr($this->_str, $this->_pos, $this->strlen($this->_str));
 	}

wp-includes/pomo/translations.php

@@ -111,6 +111,9 @@ class Translations {
 		return 1 == $count? 0 : 1;
 	}
 
+	/**
+	 * @return int
+	 */
 	function get_plural_forms_count() {
 		return 2;
 	}
@@ -146,6 +149,9 @@ class Translations {
 		}
 	}
 
+	/**
+	 * @param object $other
+	 */
 	function merge_originals_with(&$other) {
 		foreach( $other->entries as $entry ) {
 			if ( !isset( $this->entries[$entry->key()] ) )
@@ -278,16 +284,33 @@ class NOOP_Translations {
 		return true;
 	}
 
+	/**
+	 *
+	 * @param string $header
+	 * @param string $value
+	 */
 	function set_header($header, $value) {
 	}
 
+	/**
+	 *
+	 * @param array $headers
+	 */
 	function set_headers($headers) {
 	}
 
+	/**
+	 * @param string $header
+	 * @return false
+	 */
 	function get_header($header) {
 		return false;
 	}
 
+	/**
+	 * @param Translation_Entry $entry
+	 * @return false
+	 */
 	function translate_entry(&$entry) {
 		return false;
 	}
@@ -300,10 +323,18 @@ class NOOP_Translations {
 		return $singular;
 	}
 
+	/**
+	 *
+	 * @param int $count
+	 * @return bool
+	 */
 	function select_plural_form($count) {
 		return 1 == $count? 0 : 1;
 	}
 
+	/**
+	 * @return int
+	 */
 	function get_plural_forms_count() {
 		return 2;
 	}
@@ -318,6 +349,9 @@ class NOOP_Translations {
 			return 1 == $count? $singular : $plural;
 	}
 
+	/**
+	 * @param object $other
+	 */
 	function merge_with(&$other) {
 	}
 }

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.3-alpha-32671';
+$wp_version = '4.3-alpha-32672';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-login.php

@@ -241,6 +241,9 @@ function login_footer($input_id = '') {
 	<?php
 }
 
+/**
+ * @since 3.0.0
+ */
 function wp_shake_js() {
 	if ( wp_is_mobile() )
 		return;
@@ -255,6 +258,9 @@ addLoadEvent(function(){ var p=new Array(15,30,15,0,-15,-30,-15,0);p=p.concat(p.
 <?php
 }
 
+/**
+ * @since 3.7.0
+ */
 function wp_login_viewport_meta() {
 	?>
 	<meta name="viewport" content="width=device-width" />