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

@@ -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'] : '';
 

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;

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 ) {

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.
+ * @param array $handles (optional) Styles to be printed.  (void) prints queue, (string) prints that style, (array of strings) prints those styles.
- * @return mixed See {@link WP_Styles::do_items()} for information.
+ * @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') )

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' );
 

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 $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 $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}}
+ * @param string $feed Optional. Feed format.
- * @return string Link to the comment feed for the current post
+ * @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);

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');

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']);

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;

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
+ * @global int $timestart Seconds and Microseconds added together from when function is called.
- * @return bool Always returns true
+ * @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:
  * <code>
@@ -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');