Twenty Fifteen: docs correction and cleanup.

Props DrewAPicture, see #30149.



git-svn-id: https://develop.svn.wordpress.org/trunk@30569 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-content/themes/twentyfifteen/functions.php

@@ -147,7 +147,7 @@ if ( ! function_exists( 'twentyfifteen_fonts_url' ) ) :
  *
  * @since Twenty Fifteen 1.0
  *
- * @return string
+ * @return string Google fonts URL for the theme.
  */
 function twentyfifteen_fonts_url() {
 	$fonts   = array();
@@ -245,6 +245,8 @@ add_action( 'wp_enqueue_scripts', 'twentyfifteen_scripts' );
  * Add featured image as background image to post navigation elements.
  *
  * @since Twenty Fifteen 1.0
+ *
+ * @see wp_add_inline_style()
  */
 function twentyfifteen_post_nav_background() {
 	if ( ! is_single() ) {
@@ -290,7 +292,6 @@ add_action( 'wp_enqueue_scripts', 'twentyfifteen_post_nav_background' );
  * @param WP_Post $item        Menu item object.
  * @param int     $depth       Depth of the menu.
  * @param array   $args        wp_nav_menu() arguments.
- *
  * @return string Menu item with possible description.
  */
 function twentyfifteen_nav_description( $item_output, $item, $depth, $args ) {
@@ -307,9 +308,8 @@ add_filter( 'walker_nav_menu_start_el', 'twentyfifteen_nav_description', 10, 4 )
  *
  * @since Twenty Fifteen 1.0
  *
- * @param string $html Search form HTML
- *
- * @return string Modified search form HTML
+ * @param string $html Search form HTML.
+ * @return string Modified search form HTML.
  */
 function twentyfifteen_search_form_modify( $html ) {
 	return str_replace( 'class="search-submit"', 'class="search-submit screen-reader-text"', $html );

src/wp-content/themes/twentyfifteen/inc/back-compat.php

@@ -1,10 +1,10 @@
 <?php
 /**
- * Twenty Fifteen back compat functionality.
+ * Twenty Fifteen back compat functionality
  *
  * Prevents Twenty Fifteen from running on WordPress versions prior to 4.1,
- * since this theme is not meant to be backward compatible beyond that
- * and relies on many newer functions and markup changes introduced in 4.1.
+ * since this theme is not meant to be backward compatible beyond that and
+ * relies on many newer functions and markup changes introduced in 4.1.
  *
  * @package WordPress
  * @subpackage Twenty_Fifteen
@@ -60,4 +60,4 @@ function twentyfifteen_preview() {
 		wp_die( sprintf( __( 'Twenty Fifteen requires at least WordPress version 4.1. You are running version %s. Please upgrade and try again.', 'twentyfifteen' ), $GLOBALS['wp_version'] ) );
 	}
 }
-add_action( 'template_redirect', 'twentyfifteen_preview' );
+add_action( 'template_redirect', 'twentyfifteen_preview' );

src/wp-content/themes/twentyfifteen/inc/custom-header.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Implement Custom Header functionality for Twenty Fifteen.
+ * Custom Header functionality for Twenty Fifteen
  *
  * @package WordPress
  * @subpackage Twenty_Fifteen
@@ -46,7 +46,8 @@ add_action( 'after_setup_theme', 'twentyfifteen_custom_header_setup' );
  * @since Twenty Fifteen 1.0
  *
  * @param string $color The original color, in 3- or 6-digit hexadecimal form.
- * @return array
+ * @return array Array containing RGB (red, green, and blue) values for the given
+ *               HEX code, empty array otherwise.
  */
 function twentyfifteen_hex2rgb( $color ) {
 	$color = trim( $color, '#' );
@@ -71,7 +72,8 @@ if ( ! function_exists( 'twentyfifteen_header_style' ) ) :
  * Styles the header image and text displayed on the blog.
  *
  * @since Twenty Fifteen 1.0
- * @see twentyfifteen_custom_header_setup().
+ *
+ * @see twentyfifteen_custom_header_setup()
  */
 function twentyfifteen_header_style() {
 	$header_image = get_header_image();
@@ -173,6 +175,8 @@ endif; // twentyfifteen_header_style
  * Enqueues front-end CSS for the header background color.
  *
  * @since Twenty Fifteen 1.0
+ *
+ * @see wp_add_inline_style()
  */
 function twentyfifteen_header_background_color_css() {
 	$color_scheme            = twentyfifteen_get_color_scheme();

src/wp-content/themes/twentyfifteen/inc/customizer.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Twenty Fifteen Customizer.
+ * Twenty Fifteen Customizer functionality
  *
  * @package WordPress
  * @subpackage Twenty_Fifteen
@@ -76,7 +76,8 @@ add_action( 'customize_register', 'twentyfifteen_customize_register', 11 );
 
 /**
  * Register color schemes for Twenty Fifteen.
- * Can be filtered with twentyfifteen_color_schemes.
+ *
+ * Can be filtered with {@see 'twentyfifteen_color_schemes'}.
  *
  * The order of colors in a colors array:
  * 1. Main Background Color.
@@ -163,11 +164,11 @@ function twentyfifteen_get_color_schemes() {
 
 if ( ! function_exists( 'twentyfifteen_get_color_scheme' ) ) :
 /**
- * Returns an array of either the current or default color scheme hex values.
+ * Get the current Twenty Fifteen color scheme.
  *
  * @since Twenty Fifteen 1.0
  *
- * @return array
+ * @return array An associative array of either the current or default color scheme hex values.
  */
 function twentyfifteen_get_color_scheme() {
 	$color_scheme_option = get_theme_mod( 'color_scheme', 'default' );
@@ -187,7 +188,7 @@ if ( ! function_exists( 'twentyfifteen_get_color_scheme_control_options' ) ) :
  *
  * @since Twenty Fifteen 1.0
  *
- * @return array
+ * @return array Array of color schemes.
  */
 function twentyfifteen_get_color_scheme_choices() {
 	$color_schemes                = twentyfifteen_get_color_schemes();
@@ -208,7 +209,6 @@ if ( ! function_exists( 'twentyfifteen_sanitize_color_scheme' ) ) :
  * @since Twenty Fifteen 1.0
  *
  * @param string $value Color scheme name value.
- *
  * @return string Color scheme name.
  */
 function twentyfifteen_sanitize_color_scheme( $value ) {
@@ -226,6 +226,8 @@ endif; // twentyfifteen_sanitize_color_scheme
  * Enqueues front-end CSS for color scheme.
  *
  * @since Twenty Fifteen 1.0
+ *
+ * @see wp_add_inline_style()
  */
 function twentyfifteen_color_scheme_css() {
 	$color_scheme_option = get_theme_mod( 'color_scheme', 'default' );
@@ -242,6 +244,7 @@ add_action( 'wp_enqueue_scripts', 'twentyfifteen_color_scheme_css' );
 
 /**
  * Binds JS listener to make Customizer color_scheme control.
+ *
  * Passes color scheme data as colorScheme global.
  *
  * @since Twenty Fifteen 1.0
@@ -265,8 +268,8 @@ add_action( 'customize_preview_init', 'twentyfifteen_customize_preview_js' );
 /**
  * Output an Underscore template for generating CSS for the color scheme.
  *
- * The template generates the css dynamically for instant display in the Customizer preview,
- * and to be saved in a `theme_mod` for display on the front-end.
+ * The template generates the css dynamically for instant display in the Customizer
+ * preview, and to be saved in a `theme_mod` for display on the front-end.
  *
  * @since Twenty Fifteen 1.0
  */

src/wp-content/themes/twentyfifteen/inc/template-tags.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * Custom template tags for this theme.
+ * Custom template tags for Twenty Fifteen
  *
  * Eventually, some of the functionality here could be replaced by core features.
  *
@@ -126,11 +126,11 @@ function twentyfifteen_entry_meta() {
 endif;
 
 /**
- * Returns true if a blog has more than 1 category.
+ * Determine whether blog/site has more than one category.
  *
  * @since Twenty Fifteen 1.0
  *
- * @return bool
+ * @return bool True of there is more than one category, false otherwise.
  */
 function twentyfifteen_categorized_blog() {
 	if ( false === ( $all_the_cool_cats = get_transient( 'twentyfifteen_categories' ) ) ) {
@@ -159,7 +159,7 @@ function twentyfifteen_categorized_blog() {
 }
 
 /**
- * Flush out the transients used in twentyfifteen_categorized_blog.
+ * Flush out the transients used in {@see twentyfifteen_categorized_blog()}.
  *
  * @since Twenty Fifteen 1.0
  */
@@ -210,7 +210,8 @@ if ( ! function_exists( 'twentyfifteen_get_link_url' ) ) :
  * Falls back to the post permalink if no URL is found in the post.
  *
  * @since Twenty Fifteen 1.0
- * @uses get_url_in_content()
+ *
+ * @see get_url_in_content()
  *
  * @return string The Link format URL.
  */
@@ -223,10 +224,11 @@ endif;
 
 if ( ! function_exists( 'twentyfifteen_excerpt_more' ) && ! is_admin() ) :
 /**
- * Replaces "[...]" (appended to automatically generated excerpts) with ... and a Continue reading link.
+ * Replaces "[...]" (appended to automatically generated excerpts) with ... and a 'Continue reading' link.
  *
  * @since Twenty Fifteen 1.0
  *
+ * @return string 'Continue reading' link prepended with an ellipsis.
  */
 function twentyfifteen_excerpt_more( $more ) {
 	$link = sprintf( '<a href="%1$s" class="more-link">%2$s</a>',