Twenty Fifteen: Use third-person singular verbs for function descriptions.

Reference: [https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#documenting-tips PHP Documentation Standards: Documenting Tips].

Props vladimiraus, mukesh27, SergeyBiryukov.
See #63692.

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

Author: SergeyBiryukov

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

@@ -2,7 +2,7 @@
 /**
  * Twenty Fifteen functions and definitions
  *
- * Set up the theme and provides some helper functions, which are used in the
+ * Sets up the theme and provides some helper functions, which are used in the
  * theme as custom template tags. Others are attached to action and filter
  * hooks in WordPress to change core functionality.
  *
@@ -338,7 +338,7 @@ function twentyfifteen_setup() {
 add_action( 'after_setup_theme', 'twentyfifteen_setup' );
 
 /**
- * Register widget area.
+ * Registers widget area.
  *
  * @since Twenty Fifteen 1.0
  *
@@ -361,7 +361,7 @@ function twentyfifteen_widgets_init() {
 
 if ( ! function_exists( 'twentyfifteen_fonts_url' ) ) :
 	/**
-	 * Register fonts for Twenty Fifteen.
+	 * Registers fonts for Twenty Fifteen.
 	 *
 	 * @since Twenty Fifteen 1.0
 	 * @since Twenty Fifteen 3.4 Replaced Google URL with self-hosted fonts.
@@ -417,7 +417,7 @@ function twentyfifteen_javascript_detection() {
 add_action( 'wp_head', 'twentyfifteen_javascript_detection', 0 );
 
 /**
- * Enqueue scripts and styles.
+ * Enqueues scripts and styles.
  *
  * @since Twenty Fifteen 1.0
  */
@@ -478,7 +478,7 @@ function twentyfifteen_scripts() {
 add_action( 'wp_enqueue_scripts', 'twentyfifteen_scripts' );
 
 /**
- * Enqueue styles for the block-based editor.
+ * Enqueues styles for the block-based editor.
  *
  * @since Twenty Fifteen 2.1
  */
@@ -493,7 +493,7 @@ function twentyfifteen_block_editor_styles() {
 
 
 /**
- * Add preconnect for Google Fonts.
+ * Adds preconnect for Google Fonts.
  *
  * @since Twenty Fifteen 1.7
  * @deprecated Twenty Fifteen 3.4 Disabled filter because, by default, fonts are self-hosted.
@@ -519,7 +519,7 @@ function twentyfifteen_resource_hints( $urls, $relation_type ) {
 // add_filter( 'wp_resource_hints', 'twentyfifteen_resource_hints', 10, 2 );
 
 /**
- * Add featured image as background image to post navigation elements.
+ * Adds featured image as background image to post navigation elements.
  *
  * @since Twenty Fifteen 1.0
  *
@@ -561,7 +561,7 @@ function twentyfifteen_post_nav_background() {
 add_action( 'wp_enqueue_scripts', 'twentyfifteen_post_nav_background' );
 
 /**
- * Display descriptions in main navigation.
+ * Displays descriptions in main navigation.
  *
  * @since Twenty Fifteen 1.0
  *
@@ -581,7 +581,7 @@ function twentyfifteen_nav_description( $item_output, $item, $depth, $args ) {
 add_filter( 'walker_nav_menu_start_el', 'twentyfifteen_nav_description', 10, 4 );
 
 /**
- * Add a `screen-reader-text` class to the search form's submit button.
+ * Adds a `screen-reader-text` class to the search form's submit button.
  *
  * @since Twenty Fifteen 1.0
  *
@@ -657,7 +657,7 @@ function twentyfifteen_author_bio_template( $template ) {
 require get_template_directory() . '/inc/customizer.php';
 
 /**
- * Register block patterns and pattern categories.
+ * Registers block patterns and pattern categories.
  *
  * @since Twenty Fifteen 3.9
  */

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

@@ -12,7 +12,7 @@
  */
 
 /**
- * Prevent switching to Twenty Fifteen on old versions of WordPress.
+ * Prevents switching to Twenty Fifteen on old versions of WordPress.
  *
  * Switches to the default theme.
  *
@@ -26,7 +26,7 @@ function twentyfifteen_switch_theme() {
 add_action( 'after_switch_theme', 'twentyfifteen_switch_theme' );
 
 /**
- * Add message for unsuccessful theme switch.
+ * Adds message for unsuccessful theme switch.
  *
  * Prints an update nag after an unsuccessful attempt to switch to
  * Twenty Fifteen on WordPress versions prior to 4.1.
@@ -45,7 +45,7 @@ function twentyfifteen_upgrade_notice() {
 }
 
 /**
- * Prevent the Customizer from being loaded on WordPress versions prior to 4.1.
+ * Prevents the Customizer from being loaded on WordPress versions prior to 4.1.
  *
  * @since Twenty Fifteen 1.0
  */
@@ -65,7 +65,7 @@ function twentyfifteen_customize() {
 add_action( 'load-customize.php', 'twentyfifteen_customize' );
 
 /**
- * Prevent the Theme Preview from being loaded on WordPress versions prior to 4.1.
+ * Prevents the Theme Preview from being loaded on WordPress versions prior to 4.1.
  *
  * @since Twenty Fifteen 1.0
  */

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

@@ -8,7 +8,7 @@
  */
 
 /**
- * Set up the WordPress core custom header feature.
+ * Sets up the WordPress core custom header feature.
  *
  * @uses twentyfifteen_header_style()
  */
@@ -47,7 +47,7 @@ function twentyfifteen_custom_header_setup() {
 add_action( 'after_setup_theme', 'twentyfifteen_custom_header_setup' );
 
 /**
- * Convert HEX to RGB.
+ * Converts HEX to RGB.
  *
  * @since Twenty Fifteen 1.0
  *

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

@@ -8,7 +8,7 @@
  */
 
 /**
- * Add postMessage support for site title and description for the Customizer.
+ * Adds postMessage support for site title and description for the Customizer.
  *
  * @since Twenty Fifteen 1.0
  *
@@ -113,7 +113,7 @@ function twentyfifteen_customize_register( $wp_customize ) {
 add_action( 'customize_register', 'twentyfifteen_customize_register', 11 );
 
 /**
- * Render the site title for the selective refresh partial.
+ * Renders the site title for the selective refresh partial.
  *
  * @since Twenty Fifteen 1.5
  *
@@ -126,7 +126,7 @@ function twentyfifteen_customize_partial_blogname() {
 }
 
 /**
- * Render the site tagline for the selective refresh partial.
+ * Renders the site tagline for the selective refresh partial.
  *
  * @since Twenty Fifteen 1.5
  *
@@ -139,7 +139,7 @@ function twentyfifteen_customize_partial_blogdescription() {
 }
 
 /**
- * Register color schemes for Twenty Fifteen.
+ * Registers color schemes for Twenty Fifteen.
  *
  * Can be filtered with {@see 'twentyfifteen_color_schemes'}.
  *
@@ -252,7 +252,7 @@ function twentyfifteen_get_color_schemes() {
 
 if ( ! function_exists( 'twentyfifteen_get_color_scheme' ) ) :
 	/**
-	 * Get the current Twenty Fifteen color scheme.
+	 * Gets the current Twenty Fifteen color scheme.
 	 *
 	 * @since Twenty Fifteen 1.0
 	 *
@@ -770,7 +770,7 @@ function twentyfifteen_get_color_scheme_css( $colors ) {
 }
 
 /**
- * Output an Underscore template for generating CSS for the color scheme.
+ * Outputs an Underscore template for generating CSS for the color scheme.
  *
  * The template generates the css dynamically for instant display in the Customizer
  * preview.

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

@@ -11,7 +11,7 @@
 
 if ( ! function_exists( 'twentyfifteen_comment_nav' ) ) :
 	/**
-	 * Display navigation to next/previous comments when applicable.
+	 * Displays navigation to next/previous comments when applicable.
 	 *
 	 * @since Twenty Fifteen 1.0
 	 */
@@ -150,7 +150,7 @@ function twentyfifteen_entry_meta() {
 endif;
 
 /**
- * Determine whether blog/site has more than one category.
+ * Determines whether blog/site has more than one category.
  *
  * @since Twenty Fifteen 1.0
  *
@@ -186,7 +186,7 @@ function twentyfifteen_categorized_blog() {
 }
 
 /**
- * Flush out the transients used in {@see twentyfifteen_categorized_blog()}.
+ * Flushes out the transients used in {@see twentyfifteen_categorized_blog()}.
  *
  * @since Twenty Fifteen 1.0
  */
@@ -199,7 +199,7 @@ function twentyfifteen_category_transient_flusher() {
 
 if ( ! function_exists( 'twentyfifteen_post_thumbnail' ) ) :
 	/**
-	 * Display an optional post thumbnail.
+	 * Displays an optional post thumbnail.
 	 *
 	 * Wraps the post thumbnail in an anchor element on index views, or a div
 	 * element when on single views.
@@ -233,7 +233,7 @@ function twentyfifteen_post_thumbnail() {
 
 if ( ! function_exists( 'twentyfifteen_get_link_url' ) ) :
 	/**
-	 * Return the post URL.
+	 * Returns the post URL.
 	 *
 	 * Falls back to the post permalink if no URL is found in the post.
 	 *
@@ -288,7 +288,7 @@ function twentyfifteen_the_custom_logo() {
 
 if ( ! function_exists( 'wp_body_open' ) ) :
 	/**
-	 * Fire the wp_body_open action.
+	 * Fires the wp_body_open action.
 	 *
 	 * Added for backward compatibility to support pre-5.2.0 WordPress versions.
 	 *

src/wp-content/themes/twentyfifteen/js/color-scheme-control.js

@@ -1,7 +1,7 @@
 /* global colorScheme, Color */
 /**
- * Add a listener to the Color Scheme control to update other color controls to new values/defaults.
- * Also trigger an update of the Color Scheme CSS when a color is changed.
+ * Adds a listener to the Color Scheme control to update other color controls to new values/defaults.
+ * Also triggers an update of the Color Scheme CSS when a color is changed.
  */
 
 ( function( api ) {

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

@@ -92,7 +92,7 @@
 	} )();
 
 	/**
-	 * Add or remove ARIA attributes.
+	 * Adds or removes ARIA attributes.
 	 *
 	 * Uses jQuery's width() function to determine the size of the window and add
 	 * the default ARIA attributes for the menu toggle if it's visible.