Inline documentation for hooks in wp-includes/theme.php.

Props ShinichiN.
Fixes #25588.

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


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

wp-includes/theme.php

@@ -141,19 +141,24 @@ function is_child_theme() {
  * going to be the same for most cases.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'stylesheet' filter on stylesheet name.
  *
  * @return string Stylesheet name.
  */
 function get_stylesheet() {
-	return apply_filters('stylesheet', get_option('stylesheet'));
+	/**
+	 * Filter the name of current stylesheet.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $stylesheet Name of the current stylesheet.
+	 */
+	return apply_filters( 'stylesheet', get_option( 'stylesheet' ) );
 }
 
 /**
  * Retrieve stylesheet directory path for current theme.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'stylesheet_directory' filter on stylesheet directory and theme name.
  *
  * @return string Path to current theme directory.
  */
@@ -162,6 +167,15 @@ function get_stylesheet_directory() {
 	$theme_root = get_theme_root( $stylesheet );
 	$stylesheet_dir = "$theme_root/$stylesheet";
 
+	/**
+	 * Filter the stylesheet directory path for current theme.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $stylesheet_dir Absolute path to the current them.
+	 * @param string $stylesheet     Directory name of the current theme.
+	 * @param string $theme_root     Absolute path to themes directory.
+	 */
 	return apply_filters( 'stylesheet_directory', $stylesheet_dir, $stylesheet, $theme_root );
 }
 
@@ -177,6 +191,15 @@ function get_stylesheet_directory_uri() {
 	$theme_root_uri = get_theme_root_uri( $stylesheet );
 	$stylesheet_dir_uri = "$theme_root_uri/$stylesheet";
 
+	/**
+	 * Filter the stylesheet directory URI.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $stylesheet_dir_uri Stylesheet directory URI.
+	 * @param string $stylesheet         Name of the activated theme's directory.
+	 * @param string $theme_root_uri     Themes root URI.
+	 */
 	return apply_filters( 'stylesheet_directory_uri', $stylesheet_dir_uri, $stylesheet, $theme_root_uri );
 }
 
@@ -187,14 +210,21 @@ function get_stylesheet_directory_uri() {
  * get_stylesheet_directory_uri() stylesheet directory URI} path.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'stylesheet_uri' filter on stylesheet URI path and stylesheet directory URI.
  *
  * @return string
  */
 function get_stylesheet_uri() {
 	$stylesheet_dir_uri = get_stylesheet_directory_uri();
 	$stylesheet_uri = $stylesheet_dir_uri . '/style.css';
-	return apply_filters('stylesheet_uri', $stylesheet_uri, $stylesheet_dir_uri);
+	/**
+	 * Filter the URI of the current theme stylesheet.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $stylesheet_uri     Stylesheet URI for the current theme/child theme.
+	 * @param string $stylesheet_dir_uri Stylesheet directory URI for the current theme/child theme.
+	 */
+	return apply_filters( 'stylesheet_uri', $stylesheet_uri, $stylesheet_dir_uri );
 }
 
 /**
@@ -212,7 +242,6 @@ function get_stylesheet_uri() {
  * separate folder, then change the latter.
  *
  * @since 2.1.0
- * @uses apply_filters() Calls 'locale_stylesheet_uri' filter on stylesheet URI path and stylesheet directory URI.
  *
  * @return string
  */
@@ -227,7 +256,15 @@ function get_locale_stylesheet_uri() {
 		$stylesheet_uri = "$stylesheet_dir_uri/{$wp_locale->text_direction}.css";
 	else
 		$stylesheet_uri = '';
-	return apply_filters('locale_stylesheet_uri', $stylesheet_uri, $stylesheet_dir_uri);
+	/**
+	 * Filter the localized stylesheet URI.
+	 *
+	 * @since 2.1.0
+	 *
+	 * @param string $stylesheet_uri     Localized stylesheet URI.
+	 * @param string $stylesheet_dir_uri Stylesheet directory URI.
+	 */
+	return apply_filters( 'locale_stylesheet_uri', $stylesheet_uri, $stylesheet_dir_uri );
 }
 
 /**
@@ -239,14 +276,20 @@ function get_locale_stylesheet_uri() {
  * @return string Template name.
  */
 function get_template() {
-	return apply_filters('template', get_option('template'));
+	/**
+	 * Filter the name of the current theme.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $template Current theme's directory name.
+	 */
+	return apply_filters( 'template', get_option( 'template' ) );
 }
 
 /**
  * Retrieve current theme directory.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'template_directory' filter on template directory path and template name.
  *
  * @return string Template directory path.
  */
@@ -255,6 +298,15 @@ function get_template_directory() {
 	$theme_root = get_theme_root( $template );
 	$template_dir = "$theme_root/$template";
 
+	/**
+	 * Filter the current theme directory path.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $template_dir The URI of the current theme directory.
+	 * @param string $template     Directory name of the current theme.
+	 * @param string $theme_root   Absolute path to the themes directory.
+	 */
 	return apply_filters( 'template_directory', $template_dir, $template, $theme_root );
 }
 
@@ -262,7 +314,6 @@ function get_template_directory() {
  * Retrieve theme directory URI.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'template_directory_uri' filter on template directory URI path and template name.
  *
  * @return string Template directory URI.
  */
@@ -271,6 +322,15 @@ function get_template_directory_uri() {
 	$theme_root_uri = get_theme_root_uri( $template );
 	$template_dir_uri = "$theme_root_uri/$template";
 
+	/**
+	 * Filter the current theme directory URI.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $template_dir_uri The URI of the current theme directory.
+	 * @param string $template         Directory name of the current theme.
+	 * @param string $theme_root_uri   The themes root URI.
+	 */
 	return apply_filters( 'template_directory_uri', $template_dir_uri, $template, $theme_root_uri );
 }
 
@@ -350,6 +410,14 @@ function search_theme_directories( $force = false ) {
 			$relative_theme_roots[ $theme_root ] = $theme_root;
 	}
 
+	/**
+	 * Filter whether to get the cache of the registered theme directories.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @param bool   $cache_expiration Whether to get the cache of the theme directories. Default false.
+	 * @param string $cache_directory  Directory to be searched for the cache.
+	 */
 	if ( $cache_expiration = apply_filters( 'wp_cache_themes_persistently', false, 'search_theme_directories' ) ) {
 		$cached_roots = get_site_transient( 'theme_roots' );
 		if ( is_array( $cached_roots ) ) {
@@ -441,7 +509,6 @@ function search_theme_directories( $force = false ) {
  * Does not have trailing slash.
  *
  * @since 1.5.0
- * @uses apply_filters() Calls 'theme_root' filter on path.
  *
  * @param string $stylesheet_or_template The stylesheet or template name of the theme
  * @return string Theme path.
@@ -458,6 +525,13 @@ function get_theme_root( $stylesheet_or_template = false ) {
 		$theme_root = WP_CONTENT_DIR . '/themes';
 	}
 
+	/**
+	 * Filter the absolute path to the themes directory.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $theme_root Absolute path to themes directory.
+	 */
 	return apply_filters( 'theme_root', $theme_root );
 }
 
@@ -498,7 +572,16 @@ function get_theme_root_uri( $stylesheet_or_template = false, $theme_root = fals
 		$theme_root_uri = content_url( 'themes' );
 	}
 
-	return apply_filters( 'theme_root_uri', $theme_root_uri, get_option('siteurl'), $stylesheet_or_template );
+	/**
+	 * Filter the URI for themes directory.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string $theme_root_uri         The URI for themes directory.
+	 * @param string $siteurl                WordPress web address which is set in General Options.
+	 * @param string $stylesheet_or_template Stylesheet or template name of the theme.
+	 */
+	return apply_filters( 'theme_root_uri', $theme_root_uri, get_option( 'siteurl' ), $stylesheet_or_template );
 }
 
 /**
@@ -665,7 +748,6 @@ function preview_theme_ob_filter_callback( $matches ) {
  * of two arguments: $template then $stylesheet. This is for backwards compatibility.
  *
  * @since 2.5.0
- * @uses do_action() Calls 'switch_theme' action, passing the new theme.
  *
  * @param string $stylesheet Stylesheet name
  */
@@ -706,6 +788,14 @@ function switch_theme( $stylesheet ) {
 	}
 
 	update_option( 'theme_switched', $old_theme->get_stylesheet() );
+	/**
+	 * Fires after the theme is switched.
+	 *
+	 * @since 1.5.0
+	 *
+	 * @param string   $new_name  Name of the new theme.
+	 * @param WP_Theme $new_theme WP_Theme instance of the new theme.
+	 */
 	do_action( 'switch_theme', $new_name, $new_theme );
 }
 
@@ -723,8 +813,14 @@ function switch_theme( $stylesheet ) {
  * @return bool
  */
 function validate_current_theme() {
-	// Don't validate during an install/upgrade.
+	/**
-	if ( defined('WP_INSTALLING') || !apply_filters( 'validate_current_theme', true ) )
+	 * Filter whether to validate the current theme.
+	 *
+	 * @since 2.7.0
+	 *
+	 * @param bool true Validation flag to check the current theme.
+	 */
+	if ( defined('WP_INSTALLING') || ! apply_filters( 'validate_current_theme', true ) )
 		return true;
 
 	if ( get_template() != WP_DEFAULT_THEME && !file_exists(get_template_directory() . '/index.php') ) {
@@ -776,7 +872,6 @@ function get_theme_mods() {
  * directory URI.
  *
  * @since 2.1.0
- * @uses apply_filters() Calls 'theme_mod_$name' filter on the value.
  *
  * @param string $name Theme modification name.
  * @param bool|string $default
@@ -785,13 +880,27 @@ function get_theme_mods() {
 function get_theme_mod( $name, $default = false ) {
 	$mods = get_theme_mods();
 
-	if ( isset( $mods[ $name ] ) )
+	if ( isset( $mods[$name] ) ) {
-		return apply_filters( "theme_mod_$name", $mods[ $name ] );
+		/**
+		 * Filter the theme modification, or 'theme_mod', value.
+		 *
+		 * The dynamic portion of the hook name, $name, refers to
+		 * the key name of the modification array. For example,
+		 * 'header_textcolor', 'header_image', and so on depending
+		 * on the theme options.
+		 *
+		 * @since 2.2.0
+		 *
+		 * @param string $current_mod The value of the current theme modification.
+		 */
+		return apply_filters( "theme_mod_{$name}", $mods[$name] );
+	}
 
 	if ( is_string( $default ) )
 		$default = sprintf( $default, get_template_directory_uri(), get_stylesheet_directory_uri() );
 
-	return apply_filters( "theme_mod_$name", $default );
+	/** This filter is documented in wp-includes/theme.php */
+	return apply_filters( "theme_mod_{$name}", $default );
 }
 
 /**
@@ -1593,7 +1702,21 @@ function current_theme_supports( $feature ) {
 			break;
 	}
 
-	return apply_filters('current_theme_supports-' . $feature, true, $args, $_wp_theme_features[$feature]);
+	/**
+	 * Filter whether the current theme supports a specific feature.
+	 *
+	 * The dynamic portion of the hook name, $feature, refers to
+	 * the specific theme feature. Possible values include 'post-formats',
+	 * 'post-thumbnails', 'custom-background', 'custom-header', 'menus',
+	 * 'automatic-feed-links', and 'html5'.
+	 *
+	 * @since 3.4.0
+	 *
+	 * @param bool   true     Whether the current theme supports the given feature. Default true.
+	 * @param array  $args    Array of arguments for the feature.
+	 * @param string $feature The theme feature.
+	 */
+	return apply_filters( "current_theme_supports-{$feature}", true, $args, $_wp_theme_features[$feature] );
 }
 
 /**
@@ -1641,10 +1764,25 @@ function check_theme_switched() {
 	if ( $stylesheet = get_option( 'theme_switched' ) ) {
 		$old_theme = wp_get_theme( $stylesheet );
 
-		if ( $old_theme->exists() )
+		if ( $old_theme->exists() ) {
-			do_action( 'after_switch_theme', $old_theme->get('Name'), $old_theme );
+			/**
-		else
+			 * Fires on the first WP load after a theme switch if the old theme still exists.
+			 *
+			 * This action fires multiple times and the parameters differs
+			 * according to the context, if the old theme exists or not.
+			 * If the old theme is missing, the parameter will be the slug
+			 * of the old theme.
+			 *
+			 * @since 3.3.0
+			 *
+			 * @param string   $old_name  Old theme name.
+			 * @param WP_Theme $old_theme WP_Theme instance of the old theme.
+			 */
+			do_action( 'after_switch_theme', $old_theme->get( 'Name' ), $old_theme );
+		} else {
+			/** This action is documented in wp-includes/theme.php */
 			do_action( 'after_switch_theme', $stylesheet );
+		}
 
 		update_option( 'theme_switched', false );
 	}