Priority fixes for various existing hook documentation.

Props kpdesign.
See #26869

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


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

wp-admin/includes/plugin-install.php

@@ -53,7 +53,7 @@ function plugins_api($action, $args = null) {
 	 *
 	 * @since 2.7.0
 	 *
-	 * @param bool|object         The result object. Default is false.
+	 * @param bool|object $result The result object. Default false.
 	 * @param string      $action The type of information being requested from the Plugin Install API.
 	 * @param object      $args   Plugin API arguments.
 	 */

wp-admin/network/admin.php

@@ -22,7 +22,7 @@ $redirect_network_admin_request = 0 !== strcasecmp( $current_blog->domain, $curr
  *
  * @since 3.2.0
  *
- * @param bool $redirect_user_admin_request Whether the request should be redirected.
+ * @param bool $redirect_network_admin_request Whether the request should be redirected.
  */
 $redirect_network_admin_request = apply_filters( 'redirect_network_admin_request', $redirect_network_admin_request );
 if ( $redirect_network_admin_request ) {

wp-admin/options-discussion.php

@@ -80,7 +80,7 @@ include( ABSPATH . 'wp-admin/admin-header.php' );
  *
  * @since 2.7.0.
  *
- * @param int $10 The maximum depth of threaded comments. Default 10.
+ * @param int $max_depth The maximum depth of threaded comments. Default 10.
  */
 $maxdeep = (int) apply_filters( 'thread_comments_depth_max', 10 );
 

wp-admin/options-writing.php

@@ -37,13 +37,7 @@ if ( apply_filters( 'enable_post_by_email_configuration', true ) ) {
 	) );
 }
 
-/**
- * Toggle site update services configuration functionality.
- *
- * @since 3.0.0
- *
- * @param bool True or false, based on whether update services configuration is enabled or not.
- */
+/** This filter is documented in wp-admin/options-writing.php */
 if ( apply_filters( 'enable_update_services_configuration', true ) ) {
 	get_current_screen()->add_help_tab( array(
 		'id'      => 'options-services',
@@ -167,7 +161,13 @@ wp_dropdown_categories(array('hide_empty' => 0, 'name' => 'default_email_categor
 <?php } ?>
 
 <?php
-/** This filter is documented in wp-admin/options-writing.php */
+/**
+ * Filter whether to enable the Update Services section in the Writing settings screen.
+ *
+ * @since 3.0.0
+ *
+ * @param bool $enable Whether to enable the Update Services settings area. Default true.
+ */
 if ( apply_filters( 'enable_update_services_configuration', true ) ) {
 ?>
 <h3 class="title"><?php _e('Update Services') ?></h3>

wp-admin/options.php

@@ -108,11 +108,11 @@ if ( !is_multisite() ) {
 	$whitelist_options['general'][] = 'WPLANG';
 
 	/**
-	 * Toggle post-by-email functionality.
+	 * Filter whether the post-by-email functionality is enabled.
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param bool True or false, based on whether post-by-email configuration is enabled or not.
+	 * @param bool $enabled Whether post-by-email configuration is enabled. Default true.
 	 */
 	if ( apply_filters( 'enable_post_by_email_configuration', true ) )
 		$whitelist_options['writing'] = array_merge($whitelist_options['writing'], $mail_options);

wp-admin/user/admin.php

@@ -18,10 +18,7 @@ if ( ! is_multisite() ) {
 
 $redirect_user_admin_request = ( ( $current_blog->domain != $current_site->domain ) || ( $current_blog->path != $current_site->path ) );
 /**
- * Filter whether a user should be redirected to the Global Dashboard in Multisite.
- *
- * Users not assigned to any sites in the network will be redirected to the Global
- * Dashboard after logging in.
+ * Filter whether to redirect the request to the User Admin in Multisite.
  *
  * @since 3.2.0
  *

wp-includes/class-wp-embed.php

@@ -209,6 +209,8 @@ class WP_Embed {
 			/**
 			 * Filter whether to inspect the given URL for discoverable <link> tags.
 			 *
+			 * @since 2.9.0
+			 *
 			 * @see WP_oEmbed::discover()
 			 *
 			 * @param bool false Whether to enable <link> tag discovery. Default false.

wp-includes/class-wp-xmlrpc-server.php

@@ -5775,6 +5775,8 @@ class wp_xmlrpc_server extends IXR_Server {
 		sleep(1);
 
 		$remote_ip = preg_replace( '/[^0-9a-fA-F:., ]/', '', $_SERVER['REMOTE_ADDR'] );
+
+		/** This filter is documented in wp-includes/class-http.php */
 		$user_agent = apply_filters( 'http_headers_useragent', 'WordPress/' . $GLOBALS['wp_version'] . '; ' . get_bloginfo( 'url' ) );
 
 		// Let's check the remote site

wp-includes/comment-template.php

@@ -518,7 +518,15 @@ function get_comment_excerpt( $comment_ID = 0 ) {
 		$excerpt .= $blah[$i] . ' ';
 	}
 	$excerpt .= ($use_dotdotdot) ? '…' : '';
-	return apply_filters('get_comment_excerpt', $excerpt);
+
+	/**
+	 * Filter the retrieved comment excerpt.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $excerpt The comment excerpt text.
+	 */
+	return apply_filters( 'get_comment_excerpt', $excerpt );
 }
 
 /**
@@ -641,7 +649,7 @@ function get_comments_link( $post_id = 0 ) {
 	/**
 	 * Filter the returned post comments permalink.
 	 *
-	 * @since
+	 * @since 3.6.0
 	 *
 	 * @param string      $comments_link Post comments permalink with '#comments' appended.
 	 * @param int|WP_Post $post_id       Post ID or WP_Post object.
@@ -976,7 +984,7 @@ function comments_open( $post_id = null ) {
 	/**
 	 * Filter whether the current post is open for comments.
 	 *
-	 * @since
+	 * @since 2.5.0
 	 *
 	 * @param bool        $open    Whether the current post is open for comments.
 	 * @param int|WP_Post $post_id The post ID or WP_Post object.
@@ -997,6 +1005,15 @@ function pings_open( $post_id = null ) {
 	$_post = get_post($post_id);
 
 	$open = ( 'open' == $_post->ping_status );
+
+	/**
+	 * Filter whether the current post is open for pings.
+	 *
+	 * @since 2.5.0
+	 *
+	 * @param bool        $open    Whether the current post is open for pings.
+	 * @param int|WP_Post $post_id The post ID or WP_Post object.
+	 */
 	return apply_filters( 'pings_open', $open, $post_id );
 }
 
@@ -2055,7 +2072,9 @@ function comment_form( $args = array(), $post_id = null ) {
 	$defaults = array(
 		'fields'               => $fields,
 		'comment_field'        => '<p class="comment-form-comment"><label for="comment">' . _x( 'Comment', 'noun' ) . '</label> <textarea id="comment" name="comment" cols="45" rows="8" aria-required="true"></textarea></p>',
+		/** This filter is documented in wp-includes/link-template.php */
 		'must_log_in'          => '<p class="must-log-in">' . sprintf( __( 'You must be <a href="%s">logged in</a> to post a comment.' ), wp_login_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '</p>',
+		/** This filter is documented in wp-includes/link-template.php */
 		'logged_in_as'         => '<p class="logged-in-as">' . sprintf( __( 'Logged in as <a href="%1$s">%2$s</a>. <a href="%3$s" title="Log out of this account">Log out?</a>' ), get_edit_user_link(), $user_identity, wp_logout_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '</p>',
 		'comment_notes_before' => '<p class="comment-notes">' . __( 'Your email address will not be published.' ) . ( $req ? $required_text : '' ) . '</p>',
 		'comment_notes_after'  => '<p class="form-allowed-tags">' . sprintf( __( 'You may use these <abbr title="HyperText Markup Language">HTML</abbr> tags and attributes: %s' ), ' <code>' . allowed_tags() . '</code>' ) . '</p>',

wp-includes/l10n.php

@@ -53,7 +53,7 @@ function get_locale() {
 	if ( empty( $locale ) )
 		$locale = 'en_US';
 
-	// duplicate_hook
+	/** This filter is documented in wp-includes/l10n.php */
 	return apply_filters( 'locale', $locale );
 }
 
@@ -424,9 +424,9 @@ function load_textdomain( $domain, $mofile ) {
 	 *
 	 * @since 2.9.0
 	 *
-	 * @param boolean        Whether to override the text domain. Default false.
-	 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
-	 * @param string $mofile Path to the MO file.
+	 * @param bool   $override Whether to override the text domain. Default false.
+	 * @param string $domain   Text domain. Unique identifier for retrieving translated strings.
+	 * @param string $mofile   Path to the MO file.
 	 */
 	$plugin_override = apply_filters( 'override_load_textdomain', false, $domain, $mofile );
 
@@ -479,12 +479,12 @@ function unload_textdomain( $domain ) {
 	global $l10n;
 
 	/**
-	 * Filter text text domain for loading translation.
+	 * Filter the text domain for loading translation.
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param boolean        Whether to override unloading the text domain. Default false.
-	 * @param string $domain Text domain. Unique identifier for retrieving translated strings.
+	 * @param bool   $override Whether to override unloading the text domain. Default false.
+	 * @param string $domain   Text domain. Unique identifier for retrieving translated strings.
 	 */
 	$plugin_override = apply_filters( 'override_unload_textdomain', false, $domain );
 
@@ -591,7 +591,7 @@ function load_plugin_textdomain( $domain, $deprecated = false, $plugin_rel_path
  * @return bool True when textdomain is successfully loaded, false otherwise.
  */
 function load_muplugin_textdomain( $domain, $mu_plugin_rel_path = '' ) {
-	// duplicate_hook
+	/** This filter is documented in wp-includes/l10n.php */
 	$locale = apply_filters( 'plugin_locale', get_locale(), $domain );
 	$path = trailingslashit( WPMU_PLUGIN_DIR . '/' . ltrim( $mu_plugin_rel_path, '/' ) );