From d373d0982bc2a347dd1c11ed85df5e4f2b69eaf8 Mon Sep 17 00:00:00 2001 From: Lance Willett Date: Fri, 20 Sep 2013 19:34:10 +0000 Subject: [PATCH] Twenty Thirteen: update code comments to reflect WP inline docs standards. Props DrewAPicture, see #25256. Built from https://develop.svn.wordpress.org/trunk@25522 git-svn-id: http://core.svn.wordpress.org/trunk@25442 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-content/themes/twentythirteen/404.php | 2 +- wp-content/themes/twentythirteen/archive.php | 4 +- .../themes/twentythirteen/author-bio.php | 14 ++- wp-content/themes/twentythirteen/author.php | 12 +-- wp-content/themes/twentythirteen/category.php | 4 +- wp-content/themes/twentythirteen/comments.php | 4 +- .../themes/twentythirteen/content-aside.php | 2 +- .../themes/twentythirteen/content-audio.php | 2 +- .../themes/twentythirteen/content-chat.php | 2 +- .../themes/twentythirteen/content-gallery.php | 2 +- .../themes/twentythirteen/content-image.php | 2 +- .../themes/twentythirteen/content-link.php | 2 +- .../themes/twentythirteen/content-none.php | 2 +- .../themes/twentythirteen/content-quote.php | 2 +- .../themes/twentythirteen/content-status.php | 2 +- .../themes/twentythirteen/content-video.php | 2 +- wp-content/themes/twentythirteen/content.php | 4 +- wp-content/themes/twentythirteen/footer.php | 5 +- .../themes/twentythirteen/functions.php | 86 ++++++++++++------- wp-content/themes/twentythirteen/header.php | 2 +- wp-content/themes/twentythirteen/image.php | 4 +- .../themes/twentythirteen/inc/back-compat.php | 17 ++-- .../twentythirteen/inc/custom-header.php | 28 ++++-- wp-content/themes/twentythirteen/index.php | 4 +- wp-content/themes/twentythirteen/page.php | 2 +- wp-content/themes/twentythirteen/search.php | 2 +- .../themes/twentythirteen/sidebar-main.php | 4 +- wp-content/themes/twentythirteen/sidebar.php | 6 +- wp-content/themes/twentythirteen/single.php | 2 +- wp-content/themes/twentythirteen/tag.php | 4 +- .../twentythirteen/taxonomy-post_format.php | 4 +- 31 files changed, 144 insertions(+), 90 deletions(-) diff --git a/wp-content/themes/twentythirteen/404.php b/wp-content/themes/twentythirteen/404.php index c5c1b3db5e..eebc34b706 100644 --- a/wp-content/themes/twentythirteen/404.php +++ b/wp-content/themes/twentythirteen/404.php @@ -1,6 +1,6 @@
- +

diff --git a/wp-content/themes/twentythirteen/author.php b/wp-content/themes/twentythirteen/author.php index dd27b07aef..f4935cabb5 100644 --- a/wp-content/themes/twentythirteen/author.php +++ b/wp-content/themes/twentythirteen/author.php @@ -1,8 +1,8 @@ for posts and comments. add_theme_support( 'automatic-feed-links' ); - // Switches default core markup for search form, comment form, and comments - // to output valid HTML5. + /** + * Switches default core markup for search form, comment form, + * and comments to output valid HTML5. + */ add_theme_support( 'html5', array( 'search-form', 'comment-form', 'comment-list' ) ); - /* + /** * This theme supports all available post formats by default. * See http://codex.wordpress.org/Post_Formats */ @@ -92,7 +96,7 @@ function twentythirteen_setup() { // This theme uses wp_nav_menu() in one location. register_nav_menu( 'primary', __( 'Navigation Menu', 'twentythirteen' ) ); - /* + /** * This theme uses a custom image size for featured images, displayed on * "standard" posts and pages. */ @@ -105,7 +109,7 @@ function twentythirteen_setup() { add_action( 'after_setup_theme', 'twentythirteen_setup' ); /** - * Returns the Google font stylesheet URL, if available. + * Return the Google font stylesheet URL, if available. * * The use of Source Sans Pro and Bitter by default is localized. For languages * that use characters not supported by the font, the font can be disabled. @@ -117,13 +121,15 @@ add_action( 'after_setup_theme', 'twentythirteen_setup' ); function twentythirteen_fonts_url() { $fonts_url = ''; - /* Translators: If there are characters in your language that are not + /** + * Translators: If there are characters in your language that are not * supported by Source Sans Pro, translate this to 'off'. Do not translate * into your own language. */ $source_sans_pro = _x( 'on', 'Source Sans Pro font: on or off', 'twentythirteen' ); - /* Translators: If there are characters in your language that are not + /** + * Translators: If there are characters in your language that are not * supported by Bitter, translate this to 'off'. Do not translate into your * own language. */ @@ -149,15 +155,17 @@ function twentythirteen_fonts_url() { } /** - * Enqueues scripts and styles for front end. + * Enqueue scripts and styles for the front end. * * @since Twenty Thirteen 1.0 * * @return void */ function twentythirteen_scripts_styles() { - // Adds JavaScript to pages with the comment form to support sites with - // threaded comments (when in use). + /** + * Adds JavaScript to pages with the comment form to support + * sites with threaded comments (when in use). + */ if ( is_singular() && comments_open() && get_option( 'thread_comments' ) ) wp_enqueue_script( 'comment-reply' ); @@ -184,13 +192,15 @@ function twentythirteen_scripts_styles() { add_action( 'wp_enqueue_scripts', 'twentythirteen_scripts_styles' ); /** + * Filter the page title. + * * Creates a nicely formatted and more specific title element text for output * in head of document, based on current view. * * @since Twenty Thirteen 1.0 * * @param string $title Default title text for current view. - * @param string $sep Optional separator. + * @param string $sep Optional separator. * @return string The filtered title. */ function twentythirteen_wp_title( $title, $sep ) { @@ -216,7 +226,7 @@ function twentythirteen_wp_title( $title, $sep ) { add_filter( 'wp_title', 'twentythirteen_wp_title', 10, 2 ); /** - * Registers two widget areas. + * Register two widget areas. * * @since Twenty Thirteen 1.0 * @@ -247,7 +257,7 @@ add_action( 'widgets_init', 'twentythirteen_widgets_init' ); if ( ! function_exists( 'twentythirteen_paging_nav' ) ) : /** - * Displays navigation to next/previous set of posts when applicable. + * Display navigation to next/previous set of posts when applicable. * * @since Twenty Thirteen 1.0 * @@ -280,7 +290,7 @@ endif; if ( ! function_exists( 'twentythirteen_post_nav' ) ) : /** - * Displays navigation to next/previous post when applicable. + * Display navigation to next/previous post when applicable. * * @since Twenty Thirteen 1.0 * @@ -311,7 +321,7 @@ endif; if ( ! function_exists( 'twentythirteen_entry_meta' ) ) : /** - * Prints HTML with meta information for current post: categories, tags, permalink, author, and date. + * Print HTML with meta information for current post: categories, tags, permalink, author, and date. * * Create your own twentythirteen_entry_meta() to override in a child theme. * @@ -351,13 +361,13 @@ endif; if ( ! function_exists( 'twentythirteen_entry_date' ) ) : /** - * Prints HTML with date information for current post. + * Print HTML with date information for current post. * * Create your own twentythirteen_entry_date() to override in a child theme. * * @since Twenty Thirteen 1.0 * - * @param boolean $echo Whether to echo the date. Default true. + * @param boolean $echo (optional) Whether to echo the date. Default true. * @return string The HTML-formatted post date. */ function twentythirteen_entry_date( $echo = true ) { @@ -382,16 +392,26 @@ endif; if ( ! function_exists( 'twentythirteen_the_attached_image' ) ) : /** - * Prints the attached image with a link to the next attached image. + * Print the attached image with a link to the next attached image. * * @since Twenty Thirteen 1.0 * * @return void */ function twentythirteen_the_attached_image() { - $post = get_post(); + /** + * Filter the image attachment size to use. + * + * @since Twenty thirteen 1.0 + * + * @param array $size { + * @type int The attachment height in pixels. + * @type int The attachment width in pixels. + * } + */ $attachment_size = apply_filters( 'twentythirteen_attachment_size', array( 724, 724 ) ); $next_attachment_url = wp_get_attachment_url(); + $post = get_post(); /** * Grab the IDs of all the image attachments in a gallery so we can get the URL @@ -437,7 +457,7 @@ function twentythirteen_the_attached_image() { endif; /** - * Returns the URL from the post. + * Return the post URL. * * @uses get_url_in_content() to get the URL in the post meta (if it exists) or * the first link found in the post content. @@ -456,7 +476,7 @@ function twentythirteen_get_link_url() { } /** - * Extends the default WordPress body classes. + * Extend the default WordPress body classes. * * Adds body classes to denote: * 1. Single or multiple authors. @@ -483,7 +503,7 @@ function twentythirteen_body_class( $classes ) { add_filter( 'body_class', 'twentythirteen_body_class' ); /** - * Adjusts content_width value for video post formats and attachment templates. + * Adjust content_width value for video post formats and attachment templates. * * @since Twenty Thirteen 1.0 * @@ -515,10 +535,14 @@ function twentythirteen_customize_register( $wp_customize ) { add_action( 'customize_register', 'twentythirteen_customize_register' ); /** - * Binds JavaScript handlers to make Customizer preview reload changes - * asynchronously. + * Enqueue Javascript postMessage handlers for the Customizer. + * + * Binds JavaScript handlers to make the Customizer preview + * reload changes asynchronously. * * @since Twenty Thirteen 1.0 + * + * @return void */ function twentythirteen_customize_preview_js() { wp_enqueue_script( 'twentythirteen-customizer', get_template_directory_uri() . '/js/theme-customizer.js', array( 'customize-preview' ), '20130226', true ); diff --git a/wp-content/themes/twentythirteen/header.php b/wp-content/themes/twentythirteen/header.php index 52fce701eb..e19703c792 100644 --- a/wp-content/themes/twentythirteen/header.php +++ b/wp-content/themes/twentythirteen/header.php @@ -1,6 +1,6 @@ section and everything up till
* diff --git a/wp-content/themes/twentythirteen/image.php b/wp-content/themes/twentythirteen/image.php index 4ef31c4bc2..b2d86bf99d 100644 --- a/wp-content/themes/twentythirteen/image.php +++ b/wp-content/themes/twentythirteen/image.php @@ -1,8 +1,8 @@ Header admin panel. + * Style the header image displayed on the Appearance > Header admin panel. * * @since Twenty Thirteen 1.0 + * + * @return void */ function twentythirteen_admin_header_style() { $header_image = get_header_image(); @@ -198,10 +207,13 @@ function twentythirteen_admin_header_style() { } /** - * Outputs markup to be displayed on the Appearance > Header admin panel. + * Output markup to be displayed on the Appearance > Header admin panel. + * * This callback overrides the default markup displayed there. * * @since Twenty Thirteen 1.0 + * + * @return void */ function twentythirteen_admin_header_image() { ?> diff --git a/wp-content/themes/twentythirteen/index.php b/wp-content/themes/twentythirteen/index.php index 67faeafb2c..d59c10834b 100644 --- a/wp-content/themes/twentythirteen/index.php +++ b/wp-content/themes/twentythirteen/index.php @@ -1,13 +1,13 @@