From 42d51a4f890c17db7839cb50333e9bfdd9b5d5d4 Mon Sep 17 00:00:00 2001 From: Scott Taylor Date: Sun, 31 May 2015 03:18:25 +0000 Subject: [PATCH] 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 | 3 +++ wp-admin/includes/dashboard.php | 9 +++++++ wp-admin/includes/media.php | 7 ++++++ wp-admin/includes/misc.php | 9 +++++++ wp-admin/includes/ms-deprecated.php | 11 +++++++++ wp-admin/includes/plugin-install.php | 3 +++ wp-admin/includes/plugin.php | 7 ++++++ wp-admin/includes/theme-install.php | 3 +++ wp-admin/includes/update.php | 11 +++++++++ wp-admin/update-core.php | 15 +++++++++++ wp-includes/compat.php | 11 +++++++++ wp-includes/locale.php | 3 +++ wp-includes/pomo/entry.php | 3 +++ wp-includes/pomo/mo.php | 37 ++++++++++++++++++++++++++++ wp-includes/pomo/streams.php | 28 ++++++++++++++++++++- wp-includes/pomo/translations.php | 34 +++++++++++++++++++++++++ wp-includes/version.php | 2 +- wp-login.php | 6 +++++ 18 files changed, 200 insertions(+), 2 deletions(-) diff --git a/wp-admin/includes/comment.php b/wp-admin/includes/comment.php index 4208e5a214..36954b231c 100644 --- a/wp-admin/includes/comment.php +++ b/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' ); diff --git a/wp-admin/includes/dashboard.php b/wp-admin/includes/dashboard.php index 18702b32aa..03929ad8bc 100644 --- a/wp-admin/includes/dashboard.php +++ b/wp-admin/includes/dashboard.php @@ -355,6 +355,9 @@ function wp_dashboard_right_now() { var _wpColorScheme = ' . wp_json_encode( array( 'icons' => $icon_colors ) ) . ";\n"; } +/** + * @since 3.3.0 + */ function _ipad_meta() { if ( wp_is_mobile() ) { ?> diff --git a/wp-admin/includes/ms-deprecated.php b/wp-admin/includes/ms-deprecated.php index 6a443dee61..5038ad376f 100644 --- a/wp-admin/includes/ms-deprecated.php +++ b/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() {} \ No newline at end of file diff --git a/wp-admin/includes/plugin-install.php b/wp-admin/includes/plugin-install.php index 21f7176f96..a6dbabb0cc 100644 --- a/wp-admin/includes/plugin-install.php +++ b/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() { ?>

WordPress Plugin Directory or upload a plugin in .zip format via this page.' ), 'https://wordpress.org/plugins/', self_admin_url( 'plugin-install.php?tab=upload' ) ); ?>

diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php index e1a07dc4e7..ef6494e635 100644 --- a/wp-admin/includes/plugin.php +++ b/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) ) diff --git a/wp-admin/includes/theme-install.php b/wp-admin/includes/theme-install.php index 563eef15e2..5ae364d33d 100644 --- a/wp-admin/includes/theme-install.php +++ b/wp-admin/includes/theme-install.php @@ -135,6 +135,9 @@ function install_themes_dashboard() {

diff --git a/wp-admin/includes/update.php b/wp-admin/includes/update.php index 0b01d72966..943e19cd26 100644 --- a/wp-admin/includes/update.php +++ b/wp-admin/includes/update.php @@ -259,6 +259,11 @@ function update_right_now_message() { echo "

$msg

"; } +/** + * @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; diff --git a/wp-admin/update-core.php b/wp-admin/update-core.php index 413b1a648e..c4da56a4b3 100644 --- a/wp-admin/update-core.php +++ b/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() {

' . 'The build directory of the develop repository must be used for RTL.' . '

'; } diff --git a/wp-includes/pomo/entry.php b/wp-includes/pomo/entry.php index 097e92ca55..56e6f6212e 100644 --- a/wp-includes/pomo/entry.php +++ b/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 ) ); diff --git a/wp-includes/pomo/mo.php b/wp-includes/pomo/mo.php index e8eecc19d5..1757061960 100644 --- a/wp-includes/pomo/mo.php +++ b/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; } diff --git a/wp-includes/pomo/streams.php b/wp-includes/pomo/streams.php index 8e50ab4eac..381d02ad39 100644 --- a/wp-includes/pomo/streams.php +++ b/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)); } diff --git a/wp-includes/pomo/translations.php b/wp-includes/pomo/translations.php index c01a87fea3..8db80c85a6 100644 --- a/wp-includes/pomo/translations.php +++ b/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) { } } diff --git a/wp-includes/version.php b/wp-includes/version.php index e31421fe0c..afb1e99b5a 100644 --- a/wp-includes/version.php +++ b/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. diff --git a/wp-login.php b/wp-login.php index d52ccb3a4a..2056852726 100644 --- a/wp-login.php +++ b/wp-login.php @@ -241,6 +241,9 @@ function login_footer($input_id = '') {