Index: src/wp-content/themes/twentyfourteen/archive.php =================================================================== --- src/wp-content/themes/twentyfourteen/archive.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/archive.php (working copy) @@ -45,14 +45,22 @@ " > " >

', '

' ); ?> Index: src/wp-content/themes/twentyfourteen/featured-content.php =================================================================== --- src/wp-content/themes/twentyfourteen/featured-content.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/featured-content.php (working copy) @@ -11,15 +11,26 @@
$post ) : setup_postdata( $post ); + // Include the featured content template. get_template_part( 'content', 'featured-post' ); endforeach; + /** + * Fires after the Twenty Fourteen featured content. + * + * @since Twenty Fourteen 1.0 + */ do_action( 'twentyfourteen_featured_posts_after' ); wp_reset_postdata(); Index: src/wp-content/themes/twentyfourteen/functions.php =================================================================== --- src/wp-content/themes/twentyfourteen/functions.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/functions.php (working copy) @@ -6,13 +6,14 @@ * theme as custom template tags. Others are attached to action and filter * hooks in WordPress to change core functionality. * - * When using a child theme (see http://codex.wordpress.org/Theme_Development - * and http://codex.wordpress.org/Child_Themes), you can override certain - * functions (those wrapped in a function_exists() call) by defining them first - * in your child theme's functions.php file. The child theme's functions.php - * file is included before the parent theme's file, so the child theme - * functions would be used. + * When using a child theme you can override certain functions (those wrapped + * in a function_exists() call) by defining them first in your child theme's + * functions.php file. The child theme's functions.php file is included before + * the parent theme's file, so the child theme functions would be used. * + * @link http://codex.wordpress.org/Theme_Development + * @link http://codex.wordpress.org/Child_Themes + * * Functions that are not pluggable (not wrapped in function_exists()) are * instead attached to a filter or action hook. * @@ -27,7 +28,7 @@ /** * Set up the content width value based on the theme's design. * - * @link twentyfourteen_content_width() + * @see twentyfourteen_content_width() * * @since Twenty Fourteen 1.0 */ @@ -138,6 +139,13 @@ * @return array An array of WP_Post objects. */ function twentyfourteen_get_featured_posts() { + /** + * Filter the featured posts to return in Twenty Fourteen. + * + * @since Twenty Fourteen 1.0 + * + * @param array|bool $posts Array of featured posts, otherwise false. + */ return apply_filters( 'twentyfourteen_get_featured_posts', array() ); } @@ -149,11 +157,12 @@ * @return bool Whether there are featured posts. */ function twentyfourteen_has_featured_posts() { + /** This filter is documented in functions.php */ return ! is_paged() && (bool) apply_filters( 'twentyfourteen_get_featured_posts', false ); } /** - * Register two widget areas. + * Register two Twenty Fourteen widget areas. * * @since Twenty Fourteen 1.0 * @@ -214,7 +223,7 @@ } /** - * Enqueue scripts and styles for front end. + * Enqueue scripts and styles for the front end. * * @since Twenty Fourteen 1.0 * @@ -280,6 +289,18 @@ */ function twentyfourteen_the_attached_image() { $post = get_post(); + /** + * Filter the default Twenty Fourteen attachment size. + * + * @since Twenty Fourteen 1.0 + * + * @param array $dimensions { + * An array of height and width dimensions. + * + * @type int $height Height of the image in pixels. Default 1200. + * @type int $width Width of the image in pixels. Default 1200. + * } + */ $attachment_size = apply_filters( 'twentyfourteen_attachment_size', array( 1200, 1200 ) ); $next_attachment_url = wp_get_attachment_url(); Index: src/wp-content/themes/twentyfourteen/image.php =================================================================== --- src/wp-content/themes/twentyfourteen/image.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/image.php (working copy) @@ -7,6 +7,7 @@ * @since Twenty Fourteen 1.0 */ +// Retrieve attachment metadata. $metadata = wp_get_attachment_metadata(); get_header(); @@ -15,8 +16,10 @@
- - +
>
', '' ); ?> Index: src/wp-content/themes/twentyfourteen/inc/custom-header.php =================================================================== --- src/wp-content/themes/twentyfourteen/inc/custom-header.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/inc/custom-header.php (working copy) @@ -17,6 +17,24 @@ * @uses twentyfourteen_admin_header_image() */ function twentyfourteen_custom_header_setup() { + /** + * Filter Twenty Fourteen custom-header support arguments. + * + * @since Twenty Fourteen 1.0 + * + * @param array $args { + * An array of custom-header support arguments. + * + * @type bool $header_text Whether to display custom header text. Default false. + * @type int $width Width in pixels of the custom header image. Default 1260. + * @type int $height Height in pixels of the custom header image. Default 240. + * @type bool $flex_height Whether to allow flexible-height header images. Default true. + * @type string $admin_head_callback Callback function used to style the image displayed in + * the Appearance > Header screen. + * @type string $admin_preview_callback Callback function used to create the custom header markup in + * the Appearance > Header screen. + * } + */ add_theme_support( 'custom-header', apply_filters( 'twentyfourteen_custom_header_args', array( 'header-text' => false, 'width' => 1260, @@ -30,9 +48,9 @@ if ( ! function_exists( 'twentyfourteen_admin_header_style' ) ) : /** - * Style the header image displayed on the Appearance > Header admin panel. + * Style the header image displayed on the Appearance > Header screen. * - * @link twentyfourteen_custom_header_setup(). + * @see twentyfourteen_custom_header_setup() * * @since Twenty Fourteen 1.0 */ @@ -65,9 +83,9 @@ if ( ! function_exists( 'twentyfourteen_admin_header_image' ) ) : /** - * Create the custom header image markup displayed on the Appearance > Header admin panel. + * Create the custom header image markup displayed on the Appearance > Header screen. * - * @link twentyfourteen_custom_header_setup(). + * @see twentyfourteen_custom_header_setup() * * @since Twenty Fourteen 1.0 */ Index: src/wp-content/themes/twentyfourteen/inc/customizer.php =================================================================== --- src/wp-content/themes/twentyfourteen/inc/customizer.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/inc/customizer.php (working copy) @@ -72,16 +72,19 @@ add_action( 'customize_preview_init', 'twentyfourteen_customize_preview_js' ); /** - * Tweak the brightness of a color by adjusting the RGB values by the given interval. + * Tweak the brightness of a color by adjusting the RGB + * values by the given interval. * - * Use positive values of $steps to brighten the color and negative values to darken the color. - * All three RGB values are modified by the specified steps, within the range of 0-255. The hue - * is generally maintained unless the number of steps causes one value to be capped at 0 or 255. + * Use positive values of $steps to brighten the color and negative + * values to darken the color. All three RGB values are modified by + * the specified steps, within the range of 0-255. The hue is generally + * maintained unless the number of steps causes one value to be capped + * at 0 or 255. * * @since Twenty Fourteen 1.0 * * @param string $color The original color, in 3- or 6-digit hexadecimal form. - * @param int $steps The number of steps to adjust the color by, in RGB units. + * @param int $steps The number of steps to adjust the color by, in RGB units. * @return string $color The new color, in 6-digit hexadecimal form. */ function twentyfourteen_adjust_color( $color, $steps ) { @@ -109,30 +112,30 @@ } /** - * Returns a slightly lighter color than what is set as the theme's + * Return a slightly lighter color than what is set as the theme's * accent color. * * @since Twenty Fourteen 1.0 * - * @return string + * @return string Hex color. */ function twentyfourteen_accent_mid() { return twentyfourteen_adjust_color( get_theme_mod( 'accent_color' ), 29 ); } /** - * Returns a lighter color than what is set as the theme's accent color. + * Return a lighter color than what is set as the theme's accent color. * * @since Twenty Fourteen 1.0 * - * @return string + * @return string Hex color. */ function twentyfourteen_accent_light() { return twentyfourteen_adjust_color( get_theme_mod( 'accent_color' ), 49 ); } /** - * Caches the generated variants of the theme's accent color. + * Cache the generated variants of the theme's accent color. * * @since Twenty Fourteen 1.0 * @@ -324,7 +327,7 @@ add_action( 'wp_enqueue_scripts', 'twentyfourteen_customizer_styles' ); /** - * Adds contextual help to the Themes and Post edit screens. + * Add contextual help to the Themes and Post edit screens. * * @since Twenty Fourteen 1.0 * Index: src/wp-content/themes/twentyfourteen/inc/featured-content.php =================================================================== --- src/wp-content/themes/twentyfourteen/inc/featured-content.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/inc/featured-content.php (working copy) @@ -2,37 +2,48 @@ /** * Twenty Fourteen Featured Content * - * This module allows you to define a subset of posts to be displayed in the - * theme's Featured Content area. + * This module allows you to define a subset of posts to be displayed + * in the theme's Featured Content area. * - * For maximum compatibility with different methods of posting users will - * designate a featured post tag to associate posts with. Since this tag now - * has special meaning beyond that of a normal tags, users will have the - * ability to hide it from the front-end of their site. + * For maximum compatibility with different methods of posting users + * will designate a featured post tag to associate posts with. Since + * this tag now has special meaning beyond that of a normal tags, users + * will have the ability to hide it from the front-end of their site. */ class Featured_Content { /** - * The maximum number of posts that a Featured Content area can contain. We - * define a default value here but themes can override this by defining a - * "max_posts" entry in the second parameter passed in the call to - * add_theme_support( 'featured-content' ). + * The maximum number of posts a Featured Content area can contain. * + * We define a default value here but themes can override + * this by defining a "max_posts" entry in the second parameter + * passed in the call to add_theme_support( 'featured-content' ). + * * @see Featured_Content::init() + * + * @since Twenty Fourteen 1.0 + * + * @static + * @access public + * @var int */ public static $max_posts = 15; /** - * Instantiate + * Instantiate. * * All custom functionality will be hooked into the "init" action. + * + * @static + * @access public + * @since Twenty Fourteen 1.0 */ public static function setup() { add_action( 'init', array( __CLASS__, 'init' ), 30 ); } /** - * Conditionally hook into WordPress + * Conditionally hook into WordPress. * * Theme must declare that they support this module by adding * add_theme_support( 'featured-content' ); during after_setup_theme. @@ -40,7 +51,9 @@ * If no theme support is found there is no need to hook into WordPress. * We'll just return early instead. * - * @uses Featured_Content::$max_posts + * @static + * @access public + * @since Twenty Fourteen 1.0 */ public static function init() { $theme_support = get_theme_support( 'featured-content' ); @@ -85,6 +98,10 @@ * * Has to run on wp_loaded so that the preview filters of the customizer * have a chance to alter the value. + * + * @static + * @access public + * @since Twenty Fourteen 1.0 */ public static function wp_loaded() { if ( self::get_setting( 'hide-tag' ) ) { @@ -94,11 +111,13 @@ } /** - * Get featured posts + * Get featured posts. * - * @uses Featured_Content::get_featured_post_ids() + * @static + * @access public + * @since Twenty Fourteen 1.0 * - * @return array + * @return array Array of featured posts. */ public static function get_featured_posts() { $post_ids = self::get_featured_post_ids(); @@ -124,7 +143,11 @@ * * Sets the "featured_content_ids" transient. * - * @return array Array of post IDs + * @static + * @access public + * @since Twenty Fourteen 1.0 + * + * @return array Array of post IDs. */ public static function get_featured_post_ids() { // Return array of cached results if they exist. @@ -170,9 +193,13 @@ } /** - * Returns an array with IDs of posts maked as sticky. + * Return an array with IDs of posts maked as sticky. * - * @return array + * @static + * @access public + * @since Twenty Fourteen 1.0 + * + * @return array Array of sticky posts. */ public static function get_sticky_posts() { $settings = self::get_setting(); @@ -180,25 +207,33 @@ } /** - * Delete transient + * Delete featured content ids transient. * * Hooks in the "save_post" action. + * * @see Featured_Content::validate_settings(). + * + * @static + * @access public + * @since Twenty Fourteen 1.0 */ public static function delete_transient() { delete_transient( 'featured_content_ids' ); } /** - * Exclude featured posts from the home page blog query + * Exclude featured posts from the home page blog query. * - * Filter the home page posts, and remove any featured post ID's from it. Hooked - * onto the 'pre_get_posts' action, this changes the parameters of the query - * before it gets any posts. + * Filter the home page posts, and remove any featured post ID's from it. + * Hooked onto the 'pre_get_posts' action, this changes the parameters of + * the query before it gets any posts. * - * @uses Featured_Content::get_featured_post_ids(); - * @param WP_Query $query - * @return WP_Query Possibly modified WP_Query + * @static + * @access public + * @since Twenty Fourteen 1.0 + * + * @param WP_Query $query WP_Query object. + * @return WP_Query Possibly-modified WP_Query. */ public static function pre_get_posts( $query ) { @@ -233,15 +268,20 @@ } /** - * Reset tag option when the saved tag is deleted + * Reset tag option when the saved tag is deleted. * - * It's important to mention that the transient needs to be deleted, too. - * While it may not be obvious by looking at the function alone, the transient - * is deleted by Featured_Content::validate_settings(). + * It's important to mention that the transient needs to be deleted, + * too. While it may not be obvious by looking at the function alone, + * the transient is deleted by Featured_Content::validate_settings(). * * Hooks in the "delete_post_tag" action. + * * @see Featured_Content::validate_settings(). * + * @static + * @access public + * @since Twenty Fourteen 1.0 + * * @param int $tag_id The term_id of the tag that has been deleted. * @return void */ @@ -258,13 +298,17 @@ } /** - * Hide featured tag from displaying when global terms are queried from the front-end + * Hide featured tag from displaying when global terms are queried from the front-end. * * Hooks into the "get_terms" filter. * - * @param array $terms A list of term objects. This is the return value of get_terms(). + * @static + * @access public + * @since Twenty Fourteen 1.0 + * + * @param array $terms List of term objects. This is the return value of get_terms(). * @param array $taxonomies An array of taxonomy slugs. - * @return array $terms + * @return array A filtered array of terms. * * @uses Featured_Content::get_setting() */ @@ -295,14 +339,19 @@ } /** - * Hide featured tag from display when terms associated with a post object are queried from the front-end + * Hide featured tag from display when terms associated with a post object + * are queried from the front-end. * * Hooks into the "get_the_terms" filter. * - * @param array $terms A list of term objects. This is the return value of get_the_terms(). - * @param int $id The ID field for the post object that terms are associated with. + * @static + * @access public + * @since Twenty Fourteen 1.0 + * + * @param array $terms A list of term objects. This is the return value of get_the_terms(). + * @param int $id The ID field for the post object that terms are associated with. * @param array $taxonomy An array of taxonomy slugs. - * @return array $terms + * @return array Filtered array of terms. * * @uses Featured_Content::get_setting() */ @@ -333,10 +382,11 @@ } /** - * Register custom setting on the Settings -> Reading screen + * Register custom setting on the Settings -> Reading screen. * - * @uses Featured_Content::render_form() - * @uses Featured_Content::validate_settings() + * @static + * @access public + * @since Twenty Fourteen 1.0 * * @return void */ @@ -347,6 +397,10 @@ /** * Add settings to the Customizer. * + * @static + * @access public + * @since Twenty Fourteen 1.0 + * * @param WP_Customize_Manager $wp_customize Theme Customizer object. */ public static function customize_register( $wp_customize ) { @@ -386,6 +440,8 @@ /** * Enqueue the tag suggestion script. * + * @static + * @access public * @since Twenty Fourteen 1.0 */ public static function enqueue_scripts() { @@ -393,16 +449,20 @@ } /** - * Get settings + * Get featured content settings. * - * Get all settings recognized by this module. This function will return - * all settings whether or not they have been stored in the database yet. - * This ensures that all keys are available at all times. + * Get all settings recognized by this module. This function + * will return all settings whether or not they have been stored + * in the database yet. This ensures that all keys are available + * at all times. * - * In the event that you only require one setting, you may pass its name - * as the first parameter to the function and only that value will be returned. + * In the event that you only require one setting, you may pass + * its name as the first parameter to the function and only that + * value will be returned. * - * @uses Featured_Content::sanitize_quantity() + * @static + * @access public + * @since Twenty Fourteen 1.0 * * @param string $key The key of a recognized setting. * @return mixed Array of all settings by default. A single value if passed as first parameter. @@ -429,18 +489,18 @@ } /** - * Validate settings + * Validate featured content settings. * - * Make sure that all user supplied content is in an - * expected format before saving to the database. This - * function will also delete the transient set in - * Featured_Content::get_featured_content(). + * Make sure that all user supplied content is in an expected + * format before saving to the database. This function will also + * delete the transient set in Featured_Content::get_featured_content(). * - * @uses Featured_Content::self::sanitize_quantity() - * @uses Featured_Content::self::delete_transient() + * @static + * @access public + * @since Twenty Fourteen 1.0 * - * @param array $input - * @return array $output + * @param array $input Array of settings input. + * @return array Validated settings output. */ public static function validate_settings( $input ) { $output = array(); @@ -469,18 +529,21 @@ $output['hide-tag'] = isset( $input['hide-tag'] ) && $input['hide-tag'] ? 1 : 0; + // Delete the featured post ids transient. self::delete_transient(); return $output; } /** - * Sanitize quantity + * Sanitize quantity of featured posts. * + * @static + * @access public + * @since Twenty Fourteen 1.0 + * * @param int $input The value to sanitize. * @return int A number between 1 and FeaturedContent::$max_posts. - * - * @uses Featured_Content::$max_posts */ public static function sanitize_quantity( $input ) { $quantity = absint( $input ); @@ -493,6 +556,7 @@ return $quantity; } -} +} // Featured_Content + Featured_Content::setup(); Index: src/wp-content/themes/twentyfourteen/inc/template-tags.php =================================================================== --- src/wp-content/themes/twentyfourteen/inc/template-tags.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/inc/template-tags.php (working copy) @@ -36,7 +36,8 @@ $format = $GLOBALS['wp_rewrite']->using_index_permalinks() && ! strpos( $pagenum_link, 'index.php' ) ? 'index.php/' : ''; $format .= $GLOBALS['wp_rewrite']->using_permalinks() ? user_trailingslashit( 'page/%#%', 'paged' ) : '?paged=%#%'; - $links = paginate_links( array( + // Set up paginated links. + $links = paginate_links( array( 'base' => $pagenum_link, 'format' => $format, 'total' => $GLOBALS['wp_query']->max_num_pages, @@ -109,6 +110,7 @@ echo '' . __( 'Sticky', 'twentyfourteen' ) . ''; } + // Set up and print post meta information. printf( __( ' ', 'twentyfourteen' ), esc_url( get_permalink() ), esc_attr( get_the_date( 'c' ) ), @@ -149,7 +151,7 @@ } /** - * Flush out the transients used in twentyfourteen_categorized_blog + * Flush out the transients used in twentyfourteen_categorized_blog. * * @since Twenty Fourteen 1.0 * @@ -163,9 +165,11 @@ add_action( 'save_post', 'twentyfourteen_category_transient_flusher' ); /** - * Displays an optional post thumbnail, with an anchor element - * when on index views, and a div element when on a single view. + * Display an optional post thumbnail on a single view. * + * Adds an anchor element to the post thumbnail, when on + * index views, and a div element when on a single view. + * * @since Twenty Fourteen 1.0 * * @return void Index: src/wp-content/themes/twentyfourteen/inc/widgets.php =================================================================== --- src/wp-content/themes/twentyfourteen/inc/widgets.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/inc/widgets.php (working copy) @@ -16,6 +16,7 @@ /** * The supported post formats. * + * @access private * @since Twenty Fourteen 1.0 * * @var array @@ -25,6 +26,7 @@ /** * Pluralized post format strings. * + * @access private * @since Twenty Fourteen 1.0 * * @var array @@ -65,9 +67,10 @@ /** * Output the HTML for this widget. * + * @access public * @since Twenty Fourteen 1.0 * - * @param array $args An array of standard parameters for widgets in this theme. + * @param array $args An array of standard parameters for widgets in this theme. * @param array $instance An array of settings for this widget instance. * @return void Echoes its output. */ @@ -219,14 +222,15 @@ } /** - * Deal with the settings when they are saved by the admin. Here is where - * any validation should happen. + * Deal with the settings when they are saved by the admin. * + * Here is where any validation should happen. + * * @since Twenty Fourteen 1.0 * - * @param array $new_instance - * @param array $instance - * @return array + * @param array $new_instance New widget instance. + * @param array $instance Original widget instance. + * @return array Updated widget instance. */ function update( $new_instance, $instance ) { $instance['title'] = strip_tags( $new_instance['title'] ); Index: src/wp-content/themes/twentyfourteen/index.php =================================================================== --- src/wp-content/themes/twentyfourteen/index.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/index.php (working copy) @@ -2,10 +2,11 @@ /** * The main template file * - * This is the most generic template file in a WordPress theme - * and one of the two required files for a theme (the other being style.css). - * It is used to display a page when nothing more specific matches a query. - * E.g., it puts together the home page when no home.php file exists. + * This is the most generic template file in a WordPress theme and one + * of the two required files for a theme (the other being style.css). + * It is used to display a page when nothing more specific matches a query, + * e.g., it puts together the home page when no home.php file exists. + * * @link http://codex.wordpress.org/Template_Hierarchy * * @package WordPress @@ -18,9 +19,10 @@
@@ -28,14 +30,22 @@ @@ -20,14 +21,15 @@
>

', '

' ); + // Output the authors list. twentyfourteen_list_authors(); edit_post_link( __( 'Edit', 'twentyfourteen' ), '
', '
' ); Index: src/wp-content/themes/twentyfourteen/page-templates/full-width.php =================================================================== --- src/wp-content/themes/twentyfourteen/page-templates/full-width.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/page-templates/full-width.php (working copy) @@ -13,6 +13,7 @@ @@ -20,9 +21,10 @@
Index: src/wp-content/themes/twentyfourteen/search.php =================================================================== --- src/wp-content/themes/twentyfourteen/search.php (revision 26528) +++ src/wp-content/themes/twentyfourteen/search.php (working copy) @@ -18,15 +18,23 @@

-