From 3fc6097a5ade3fe7b10838a551a69db4ef6539f8 Mon Sep 17 00:00:00 2001 From: ryan Date: Sat, 18 Oct 2008 20:46:30 +0000 Subject: [PATCH] phpdoc corrections from jacobsantos. see #7918 git-svn-id: http://svn.automattic.com/wordpress/trunk@9243 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/plugin-install.php | 7 +++- wp-includes/functions.php | 22 +++++++++---- wp-includes/functions.wp-scripts.php | 20 ++++++++++-- wp-includes/functions.wp-styles.php | 26 +++++++++++++-- wp-includes/general-template.php | 9 ++++++ wp-includes/link-template.php | 10 +++--- wp-includes/pluggable.php | 8 ++--- wp-includes/rss.php | 2 +- wp-includes/script-loader.php | 2 -- wp-settings.php | 48 +++++++++++++++++----------- 10 files changed, 110 insertions(+), 44 deletions(-) diff --git a/wp-admin/includes/plugin-install.php b/wp-admin/includes/plugin-install.php index a890f48c12..a2cf7db65b 100644 --- a/wp-admin/includes/plugin-install.php +++ b/wp-admin/includes/plugin-install.php @@ -156,7 +156,12 @@ function install_dashboard() { echo wp_generate_tag_cloud($tags, array( 'single_text' => __('%d plugin'), 'multiple_text' => __('%d plugins') ) ); } -function install_search_form($after_submit = '') { +/** + * Display search form for searching plugins. + * + * @since 2.7.0 + */ +function install_search_form(){ $type = isset($_REQUEST['type']) ? $_REQUEST['type'] : ''; $term = isset($_REQUEST['s']) ? $_REQUEST['s'] : ''; diff --git a/wp-includes/functions.php b/wp-includes/functions.php index c81aebac62..a24289e25c 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -646,12 +646,13 @@ function delete_option( $name ) { /** * Saves and restores user interface settings stored in a cookie. * + * Checks if the current user-settings cookie is updated and stores it. When no + * cookie exists (different browser used), adds the last saved cookie restoring + * the settings. + * * @package WordPress * @subpackage Option * @since 2.7.0 - * - * Checks if the current user-settings cookie is updated and stores it. - * When no cookie exists (different browser used), adds the last saved cookie restoring the settings. */ function wp_user_settings() { @@ -690,8 +691,8 @@ function wp_user_settings() { * * @package WordPress * @subpackage Option - * @since 2.7.0 - * + * @since 2.7.0 + * * @param string $name The name of the setting. * @param string $default Optional default value to return when $name is not set. * @return mixed the last saved user setting or the default value/false if it doesn't exist. @@ -706,12 +707,12 @@ function get_user_setting( $name, $default = false ) { /** * Delete user interface settings. * + * Deleting settings would reset them to the defaults. + * * @package WordPress * @subpackage Option * @since 2.7.0 * - * Deleting settings would reset them to the defaults. - * * @param mixed $names The name or array of names of the setting to be deleted. */ function delete_user_setting( $names ) { @@ -763,6 +764,13 @@ function get_all_user_settings() { return array(); } +/** + * Delete the user settings of the current user. + * + * @package WordPress + * @subpackage Option + * @since 2.7.0 + */ function delete_all_user_settings() { if ( ! $user = wp_get_current_user() ) return; diff --git a/wp-includes/functions.wp-scripts.php b/wp-includes/functions.wp-scripts.php index 4661cf779f..1f7e6aca71 100644 --- a/wp-includes/functions.wp-scripts.php +++ b/wp-includes/functions.wp-scripts.php @@ -34,6 +34,12 @@ function wp_print_scripts( $handles = false ) { return $wp_scripts->do_items( $handles ); } +/** + * Register new JavaScript file. + * + * @since r16 + * @see WP_Scripts::add() For parameter information. + */ function wp_register_script( $handle, $src, $deps = array(), $ver = false ) { global $wp_scripts; if ( !is_a($wp_scripts, 'WP_Scripts') ) @@ -43,10 +49,11 @@ function wp_register_script( $handle, $src, $deps = array(), $ver = false ) { } /** - * Localizes a script + * Localizes a script. * - * Localizes only if script has already been added + * Localizes only if script has already been added. * + * @since r16 * @see WP_Script::localize() */ function wp_localize_script( $handle, $object_name, $l10n ) { @@ -57,6 +64,12 @@ function wp_localize_script( $handle, $object_name, $l10n ) { return $wp_scripts->localize( $handle, $object_name, $l10n ); } +/** + * Remove a registered script. + * + * @since r16 + * @see WP_Scripts::remove() For parameter information. + */ function wp_deregister_script( $handle ) { global $wp_scripts; if ( !is_a($wp_scripts, 'WP_Scripts') ) @@ -66,10 +79,11 @@ function wp_deregister_script( $handle ) { } /** - * Equeues script + * Enqueues script. * * Registers the script if src provided (does NOT overwrite) and enqueues. * + * @since r16 * @see WP_Script::add(), WP_Script::enqueue() */ function wp_enqueue_script( $handle, $src = false, $deps = array(), $ver = false ) { diff --git a/wp-includes/functions.wp-styles.php b/wp-includes/functions.wp-styles.php index b1e0ae0837..af552909f8 100644 --- a/wp-includes/functions.wp-styles.php +++ b/wp-includes/functions.wp-styles.php @@ -7,12 +7,14 @@ */ /** - * {@internal Missing Short Description}} + * Display styles that are in the queue or part of $handles. * * @since r79 + * @uses do_action() Calls 'wp_print_styles' hook. + * @global object $wp_styles The WP_Styles object for printing styles. * - * @param mixed $handles See {@link WP_Styles::do_items()} for information. - * @return mixed See {@link WP_Styles::do_items()} for information. + * @param array $handles (optional) Styles to be printed. (void) prints queue, (string) prints that style, (array of strings) prints those styles. + * @return bool True on success, false on failure. */ function wp_print_styles( $handles = false ) { do_action( 'wp_print_styles' ); @@ -30,6 +32,12 @@ function wp_print_styles( $handles = false ) { return $wp_styles->do_items( $handles ); } +/** + * Register CSS style file. + * + * @since r79 + * @see WP_Styles::add() For parameter and additional information. + */ function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media = false ) { global $wp_styles; if ( !is_a($wp_styles, 'WP_Styles') ) @@ -38,6 +46,12 @@ function wp_register_style( $handle, $src, $deps = array(), $ver = false, $media $wp_styles->add( $handle, $src, $deps, $ver, $media ); } +/** + * Remove a registered CSS file. + * + * @since r79 + * @see WP_Styles::remove() For parameter and additional information. + */ function wp_deregister_style( $handle ) { global $wp_styles; if ( !is_a($wp_styles, 'WP_Styles') ) @@ -46,6 +60,12 @@ function wp_deregister_style( $handle ) { $wp_styles->remove( $handle ); } +/** + * Enqueue a CSS style file. + * + * @since r79 + * @see WP_Styles::add(), WP_Styles::enqueue() + */ function wp_enqueue_style( $handle, $src = false, $deps = array(), $ver = false, $media = false ) { global $wp_styles; if ( !is_a($wp_styles, 'WP_Styles') ) diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php index 8ef2f9f007..61c78eb8ed 100644 --- a/wp-includes/general-template.php +++ b/wp-includes/general-template.php @@ -93,6 +93,15 @@ function get_sidebar( $name = null ) { load_template( get_theme_root() . '/default/sidebar.php'); } +/** + * Display search form. + * + * Will first attempt to locate the searchform.php file in either the child or + * the parent, then load it. If it doesn't exist, then the default search form + * will be displayed. + * + * @since 2.7.0 + */ function get_search_form() { do_action( 'get_search_form' ); diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index 71c98c7ce8..026a0ff2e1 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -28,8 +28,8 @@ function the_permalink() { * @since 2.2.0 * @uses $wp_rewrite * - * @param $string string a URL with or without a trailing slash - * @param $type_of_url string the type of URL being considered (e.g. single, category, etc) for use in the filter + * @param $string String a URL with or without a trailing slash + * @param $type_of_url String the type of URL being considered (e.g. single, category, etc) for use in the filter * @return string */ function user_trailingslashit($string, $type_of_url = '') { @@ -439,10 +439,10 @@ function get_post_comments_feed_link($post_id = '', $feed = '') { * @subpackage Feed * @since 2.5.0 * - * @param string $link_text Descriptive text + * @param string $link_text Descriptive text. * @param int $post_id Optional post ID. Default to current post. - * @param string $feed Optional. {@internal Missing Description}} - * @return string Link to the comment feed for the current post + * @param string $feed Optional. Feed format. + * @return string Link to the comment feed for the current post. */ function post_comments_feed_link( $link_text = '', $post_id = '', $feed = '' ) { $url = get_post_comments_feed_link($post_id, $feed); diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index 1880926874..49d4124fa5 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -426,16 +426,16 @@ function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() } endif; +if ( !function_exists('wp_authenticate') ) : /** * Checks a user's login information and logs them in if it checks out. * - * @since 2.5 + * @since 2.5.0 * * @param string $username User's username * @param string $password User's password * @return WP_Error|WP_User WP_User object if login successful, otherwise WP_Error object. */ -if ( !function_exists('wp_authenticate') ) : function wp_authenticate($username, $password) { $username = sanitize_user($username); @@ -467,12 +467,12 @@ function wp_authenticate($username, $password) { } endif; +if ( !function_exists('wp_logout') ) : /** * Log the current user out. * - * @since 2.5 + * @since 2.5.0 */ -if ( !function_exists('wp_logout') ) : function wp_logout() { wp_clear_auth_cookie(); do_action('wp_logout'); diff --git a/wp-includes/rss.php b/wp-includes/rss.php index ca2534ed5c..60e1b759a6 100644 --- a/wp-includes/rss.php +++ b/wp-includes/rss.php @@ -17,7 +17,7 @@ */ do_action('load_feed_engine'); - +/** RSS feed constant. */ define('RSS', 'RSS'); define('ATOM', 'Atom'); define('MAGPIE_USER_AGENT', 'WordPress/' . $GLOBALS['wp_version']); diff --git a/wp-includes/script-loader.php b/wp-includes/script-loader.php index 3e1846e289..e6557cd827 100644 --- a/wp-includes/script-loader.php +++ b/wp-includes/script-loader.php @@ -298,7 +298,6 @@ function wp_default_scripts( &$scripts ) { * * @param object $styles */ - function wp_default_styles( &$styles ) { // This checks to see if site_url() returns something and if it does not // then it assigns $guess_url to wp_guess_url(). Strange format, but it works. @@ -346,7 +345,6 @@ function wp_default_styles( &$styles ) { * @param array $js_array JavaScript scripst array * @return array Reordered array, if needed. */ - function wp_prototype_before_jquery( $js_array ) { if ( false === $jquery = array_search( 'jquery', $js_array ) ) return $js_array; diff --git a/wp-settings.php b/wp-settings.php index efc7f63b17..ac5184095f 100644 --- a/wp-settings.php +++ b/wp-settings.php @@ -17,7 +17,7 @@ if ( function_exists('memory_get_usage') && ( (int) @ini_get('memory_limit') < a /** - * wp_unregister_GLOBALS() - Turn register globals off + * Turn register globals off. * * @access private * @since 2.1.0 @@ -142,12 +142,12 @@ if ( !extension_loaded('mysql') && !file_exists(WP_CONTENT_DIR . '/db.php') ) die( /*WP_I18N_OLD_MYSQL*/'Your PHP installation appears to be missing the MySQL extension which is required by WordPress.'/*/WP_I18N_OLD_MYSQL*/ ); /** - * timer_start() - PHP 4 standard microtime start capture + * PHP 4 standard microtime start capture. * * @access private * @since 0.71 - * @global int $timestart Seconds and Microseconds added together from when function is called - * @return bool Always returns true + * @global int $timestart Seconds and Microseconds added together from when function is called. + * @return bool Always returns true. */ function timer_start() { global $timestart; @@ -158,7 +158,7 @@ function timer_start() { } /** - * timer_stop() - Return and/or display the time from the page start to when function is called. + * Return and/or display the time from the page start to when function is called. * * You can get the results and print them by doing: * @@ -315,12 +315,24 @@ if ( !defined('WP_CONTENT_URL') ) /** * Allows for the plugins directory to be moved from the default location. * - * @since 2.6 + * @since 2.6.0 */ if ( !defined('WP_PLUGIN_DIR') ) define( 'WP_PLUGIN_DIR', WP_CONTENT_DIR . '/plugins' ); // full path, no trailing slash + +/** + * Allows for the plugins directory to be moved from the default location. + * + * @since 2.6.0 + */ if ( !defined('WP_PLUGIN_URL') ) define( 'WP_PLUGIN_URL', WP_CONTENT_URL . '/plugins' ); // full url, no trailing slash + +/** + * Allows for the plugins directory to be moved from the default location. + * + * @since 2.1.0 + */ if ( !defined('PLUGINDIR') ) define( 'PLUGINDIR', 'wp-content/plugins' ); // Relative to ABSPATH. For back compat. @@ -336,7 +348,7 @@ if ( ! defined('WP_INSTALLING') ) { /** * Should be exactly the same as the default value of SECRET_KEY in wp-config-sample.php - * @since 2.5 + * @since 2.5.0 */ $wp_default_secret_key = 'put your unique phrase here'; @@ -356,21 +368,21 @@ if ( !defined('PASS_COOKIE') ) /** * It is possible to define this in wp-config.php - * @since 2.5 + * @since 2.5.0 */ if ( !defined('AUTH_COOKIE') ) define('AUTH_COOKIE', 'wordpress_' . COOKIEHASH); /** * It is possible to define this in wp-config.php - * @since 2.6 + * @since 2.6.0 */ if ( !defined('SECURE_AUTH_COOKIE') ) define('SECURE_AUTH_COOKIE', 'wordpress_sec_' . COOKIEHASH); /** * It is possible to define this in wp-config.php - * @since 2.6 + * @since 2.6.0 */ if ( !defined('LOGGED_IN_COOKIE') ) define('LOGGED_IN_COOKIE', 'wordpress_logged_in_' . COOKIEHASH); @@ -398,14 +410,14 @@ if ( !defined('SITECOOKIEPATH') ) /** * It is possible to define this in wp-config.php - * @since 2.6 + * @since 2.6.0 */ if ( !defined('ADMIN_COOKIE_PATH') ) define( 'ADMIN_COOKIE_PATH', SITECOOKIEPATH . 'wp-admin' ); /** * It is possible to define this in wp-config.php - * @since 2.6 + * @since 2.6.0 */ if ( !defined('PLUGINS_COOKIE_PATH') ) define( 'PLUGINS_COOKIE_PATH', preg_replace('|https?://[^/]+|i', '', WP_PLUGIN_URL) ); @@ -419,7 +431,7 @@ if ( !defined('COOKIE_DOMAIN') ) /** * It is possible to define this in wp-config.php - * @since 2.6 + * @since 2.6.0 */ if ( !defined('FORCE_SSL_ADMIN') ) define('FORCE_SSL_ADMIN', false); @@ -427,7 +439,7 @@ force_ssl_admin(FORCE_SSL_ADMIN); /** * It is possible to define this in wp-config.php - * @since 2.6 + * @since 2.6.0 */ if ( !defined('FORCE_SSL_LOGIN') ) define('FORCE_SSL_LOGIN', false); @@ -529,13 +541,13 @@ do_action('setup_theme'); /** * Web Path to the current active template directory - * @since 1.5 + * @since 1.5.0 */ define('TEMPLATEPATH', get_template_directory()); /** * Web Path to the current active template stylesheet directory - * @since 2.1 + * @since 2.1.0 */ define('STYLESHEETPATH', get_stylesheet_directory()); @@ -568,10 +580,10 @@ if ( file_exists(TEMPLATEPATH . '/functions.php') ) include(TEMPLATEPATH . '/functions.php'); /** - * shutdown_action_hook() - Runs just before PHP shuts down execution. + * Runs just before PHP shuts down execution. * * @access private - * @since 1.2 + * @since 1.2.0 */ function shutdown_action_hook() { do_action('shutdown');