From 5e51ea994076ef17674ee9d0d38b7214bcaa07fb Mon Sep 17 00:00:00 2001 From: Drew Jaynes Date: Sat, 12 Apr 2014 00:01:15 +0000 Subject: [PATCH] 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 | 2 +- wp-admin/network/admin.php | 2 +- wp-admin/options-discussion.php | 2 +- wp-admin/options-writing.php | 16 ++++++++-------- wp-admin/options.php | 4 ++-- wp-admin/user/admin.php | 5 +---- wp-includes/class-wp-embed.php | 2 ++ wp-includes/class-wp-xmlrpc-server.php | 2 ++ wp-includes/comment-template.php | 25 ++++++++++++++++++++++--- wp-includes/l10n.php | 16 ++++++++-------- 10 files changed, 48 insertions(+), 28 deletions(-) diff --git a/wp-admin/includes/plugin-install.php b/wp-admin/includes/plugin-install.php index e72d2ad124..c17d1aeb08 100644 --- a/wp-admin/includes/plugin-install.php +++ b/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. */ diff --git a/wp-admin/network/admin.php b/wp-admin/network/admin.php index c46aa4eaa5..ad760f3e21 100644 --- a/wp-admin/network/admin.php +++ b/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 ) { diff --git a/wp-admin/options-discussion.php b/wp-admin/options-discussion.php index c1506fd945..da0801a91a 100644 --- a/wp-admin/options-discussion.php +++ b/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 ); diff --git a/wp-admin/options-writing.php b/wp-admin/options-writing.php index 301120cb94..4c761d2646 100644 --- a/wp-admin/options-writing.php +++ b/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

diff --git a/wp-admin/options.php b/wp-admin/options.php index 8b84811476..f705a9f662 100644 --- a/wp-admin/options.php +++ b/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); diff --git a/wp-admin/user/admin.php b/wp-admin/user/admin.php index 1870af01cb..1445245805 100644 --- a/wp-admin/user/admin.php +++ b/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 * diff --git a/wp-includes/class-wp-embed.php b/wp-includes/class-wp-embed.php index 2670ebe315..66b2820f3f 100644 --- a/wp-includes/class-wp-embed.php +++ b/wp-includes/class-wp-embed.php @@ -209,6 +209,8 @@ class WP_Embed { /** * Filter whether to inspect the given URL for discoverable tags. * + * @since 2.9.0 + * * @see WP_oEmbed::discover() * * @param bool false Whether to enable tag discovery. Default false. diff --git a/wp-includes/class-wp-xmlrpc-server.php b/wp-includes/class-wp-xmlrpc-server.php index 8feccfad07..0f617dbf99 100644 --- a/wp-includes/class-wp-xmlrpc-server.php +++ b/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 diff --git a/wp-includes/comment-template.php b/wp-includes/comment-template.php index f57d68be1a..978221f980 100644 --- a/wp-includes/comment-template.php +++ b/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' => '

', + /** This filter is documented in wp-includes/link-template.php */ 'must_log_in' => '

' . sprintf( __( 'You must be logged in to post a comment.' ), wp_login_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '

', + /** This filter is documented in wp-includes/link-template.php */ 'logged_in_as' => '

' . sprintf( __( 'Logged in as %2$s. Log out?' ), get_edit_user_link(), $user_identity, wp_logout_url( apply_filters( 'the_permalink', get_permalink( $post_id ) ) ) ) . '

', 'comment_notes_before' => '

' . __( 'Your email address will not be published.' ) . ( $req ? $required_text : '' ) . '

', 'comment_notes_after' => '

' . sprintf( __( 'You may use these HTML tags and attributes: %s' ), ' ' . allowed_tags() . '' ) . '

', diff --git a/wp-includes/l10n.php b/wp-includes/l10n.php index e4df76bd46..541cb15f99 100644 --- a/wp-includes/l10n.php +++ b/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, '/' ) );