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