Twenty Seventeen: 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@60533 602fd350-edb4-49c9-b593-d223f7449a82

Author: SergeyBiryukov

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

@@ -244,7 +244,7 @@ function twentyseventeen_setup() {
 add_action( 'after_setup_theme', 'twentyseventeen_setup' );
 
 /**
- * Set the content width in pixels, based on the theme's design and stylesheet.
+ * Sets the content width in pixels, based on the theme's design and stylesheet.
  *
  * Priority 0 to make it available to lower priority callbacks.
  *
@@ -284,7 +284,7 @@ function twentyseventeen_content_width() {
 
 if ( ! function_exists( 'twentyseventeen_fonts_url' ) ) :
 	/**
-	 * Register custom fonts.
+	 * Registers custom fonts.
 	 *
 	 * @since Twenty Seventeen 1.0
 	 * @since Twenty Seventeen 3.2 Replaced Google URL with self-hosted fonts.
@@ -309,7 +309,7 @@ function twentyseventeen_fonts_url() {
 endif;
 
 /**
- * Add preconnect for Google Fonts.
+ * Adds preconnect for Google Fonts.
  *
  * @since Twenty Seventeen 1.0
  * @deprecated Twenty Seventeen 3.2 Disabled filter because, by default, fonts are self-hosted.
@@ -331,7 +331,7 @@ function twentyseventeen_resource_hints( $urls, $relation_type ) {
 // add_filter( 'wp_resource_hints', 'twentyseventeen_resource_hints', 10, 2 );
 
 /**
- * Register widget area.
+ * Registers widget area.
  *
  * @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
  */
@@ -411,7 +411,7 @@ function twentyseventeen_javascript_detection() {
 add_action( 'wp_head', 'twentyseventeen_javascript_detection', 0 );
 
 /**
- * Add a pingback url auto-discovery header for singularly identifiable articles.
+ * Adds a pingback url auto-discovery header for singularly identifiable articles.
  */
 function twentyseventeen_pingback_header() {
 	if ( is_singular() && pings_open() ) {
@@ -421,7 +421,7 @@ function twentyseventeen_pingback_header() {
 add_action( 'wp_head', 'twentyseventeen_pingback_header' );
 
 /**
- * Display custom color CSS.
+ * Displays custom color CSS.
  */
 function twentyseventeen_colors_css_wrap() {
 	if ( 'custom' !== get_theme_mod( 'colorscheme' ) && ! is_customize_preview() ) {
@@ -551,7 +551,7 @@ function twentyseventeen_block_editor_styles() {
 add_action( 'enqueue_block_editor_assets', 'twentyseventeen_block_editor_styles' );
 
 /**
- * Add custom image sizes attribute to enhance responsive image functionality
+ * Adds custom image sizes attribute to enhance responsive image functionality
  * for content images.
  *
  * @since Twenty Seventeen 1.0
@@ -598,7 +598,7 @@ function twentyseventeen_header_image_tag( $html, $header, $attr ) {
 add_filter( 'get_header_image_tag', 'twentyseventeen_header_image_tag', 10, 3 );
 
 /**
- * Add custom image sizes attribute to enhance responsive image functionality
+ * Adds custom image sizes attribute to enhance responsive image functionality
  * for post thumbnails.
  *
  * @since Twenty Seventeen 1.0
@@ -622,7 +622,7 @@ function twentyseventeen_post_thumbnail_sizes_attr( $attr, $attachment, $size )
 add_filter( 'wp_get_attachment_image_attributes', 'twentyseventeen_post_thumbnail_sizes_attr', 10, 3 );
 
 /**
- * Use front-page.php when Front page displays is set to a static page.
+ * Uses front-page.php when Front page displays is set to a static page.
  *
  * @since Twenty Seventeen 1.0
  *
@@ -692,10 +692,10 @@ function wp_get_list_item_separator() {
 endif;
 
 /**
- * Show the featured image below the header on single posts and pages, unless the
- * page is the front page.
+ * Shows the featured image below the header on single posts and pages, unless
+ * the page is the front page.
  *
- * Use the filter `twentyseventeen_should_show_featured_image` in a child theme or
+ * Uses the filter `twentyseventeen_should_show_featured_image` in a child theme or
  * plugin to change when the image is shown. This example prevents the image
  * from showing:
  *
@@ -749,7 +749,7 @@ function twentyseventeen_should_show_featured_image() {
 require get_parent_theme_file_path( '/inc/icon-functions.php' );
 
 /**
- * Register block patterns and pattern categories.
+ * Registers block patterns and pattern categories.
  *
  * @since Twenty Seventeen 3.8
  */

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

@@ -12,7 +12,7 @@
  */
 
 /**
- * Prevent switching to Twenty Seventeen on old versions of WordPress.
+ * Prevents switching to Twenty Seventeen on old versions of WordPress.
  *
  * Switches to the default theme.
  *

src/wp-content/themes/twentyseventeen/inc/color-patterns.php

@@ -8,7 +8,7 @@
  */
 
 /**
- * Generate the CSS for the current custom color scheme.
+ * Generates the CSS for the current custom color scheme.
  */
 function twentyseventeen_custom_colors_css() {
 	$hue = absint( get_theme_mod( 'colorscheme_hue', 250 ) );

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

@@ -10,7 +10,7 @@
  */
 
 /**
- * Set up the WordPress core custom header feature.
+ * Sets up the WordPress core custom header feature.
  *
  * @uses twentyseventeen_header_style()
  */
@@ -118,7 +118,7 @@ function twentyseventeen_header_style() {
 endif; // End of twentyseventeen_header_style().
 
 /**
- * Customize video play/pause button in the custom header.
+ * Customizes video play/pause button in the custom header.
  *
  * @param array $settings Video settings.
  * @return array The filtered video settings.

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

@@ -8,7 +8,7 @@
  */
 
 /**
- * Add postMessage support for site title and description for the Theme Customizer.
+ * Adds postMessage support for site title and description for the Theme Customizer.
  *
  * @param WP_Customize_Manager $wp_customize Theme Customizer object.
  */
@@ -162,7 +162,7 @@ function twentyseventeen_customize_register( $wp_customize ) {
 add_action( 'customize_register', 'twentyseventeen_customize_register' );
 
 /**
- * Sanitize the page layout options.
+ * Sanitizes the page layout options.
  *
  * @param string $input Page layout.
  */
@@ -180,7 +180,7 @@ function twentyseventeen_sanitize_page_layout( $input ) {
 }
 
 /**
- * Sanitize the colorscheme.
+ * Sanitizes the colorscheme.
  *
  * @param string $input Color scheme.
  */
@@ -195,7 +195,7 @@ function twentyseventeen_sanitize_colorscheme( $input ) {
 }
 
 /**
- * Render the site title for the selective refresh partial.
+ * Renders the site title for the selective refresh partial.
  *
  * @since Twenty Seventeen 1.0
  *
@@ -208,7 +208,7 @@ function twentyseventeen_customize_partial_blogname() {
 }
 
 /**
- * Render the site tagline for the selective refresh partial.
+ * Renders the site tagline for the selective refresh partial.
  *
  * @since Twenty Seventeen 1.0
  *
@@ -221,7 +221,7 @@ function twentyseventeen_customize_partial_blogdescription() {
 }
 
 /**
- * Return whether we're previewing the front page and it's a static page.
+ * Returns whether we're previewing the front page and it's a static page.
  *
  * This function is an alias for twentyseventeen_is_frontpage().
  *
@@ -235,23 +235,23 @@ function twentyseventeen_is_static_front_page() {
 }
 
 /**
- * Return whether we're on a view that supports a one or two column layout.
+ * Returns whether we're on a view that supports a one or two column layout.
  */
 function twentyseventeen_is_view_with_layout_option() {
 	// This option is available on all pages. It's also available on archives when there isn't a sidebar.
 	return ( is_page() || ( is_archive() && ! is_active_sidebar( 'sidebar-1' ) ) );
 }
 
 /**
- * Bind JS handlers to instantly live-preview changes.
+ * Binds JS handlers to instantly live-preview changes.
  */
 function twentyseventeen_customize_preview_js() {
 	wp_enqueue_script( 'twentyseventeen-customize-preview', get_theme_file_uri( '/assets/js/customize-preview.js' ), array( 'customize-preview' ), '20161002', array( 'in_footer' => true ) );
 }
 add_action( 'customize_preview_init', 'twentyseventeen_customize_preview_js' );
 
 /**
- * Load dynamic logic for the customizer controls area.
+ * Loads dynamic logic for the customizer controls area.
  */
 function twentyseventeen_panels_js() {
 	wp_enqueue_script( 'twentyseventeen-customize-controls', get_theme_file_uri( '/assets/js/customize-controls.js' ), array(), '20161020', array( 'in_footer' => true ) );

src/wp-content/themes/twentyseventeen/inc/icon-functions.php

@@ -8,7 +8,7 @@
  */
 
 /**
- * Add SVG definitions to the footer.
+ * Adds SVG definitions to the footer.
  */
 function twentyseventeen_include_svg_icons() {
 	// Define SVG sprite file.
@@ -22,7 +22,7 @@ function twentyseventeen_include_svg_icons() {
 add_action( 'wp_footer', 'twentyseventeen_include_svg_icons', 9999 );
 
 /**
- * Return SVG markup.
+ * Returns SVG markup.
  *
  * @param array $args {
  *     Parameters needed to display an SVG.
@@ -115,7 +115,7 @@ function twentyseventeen_get_svg( $args = array() ) {
 }
 
 /**
- * Display SVG icons in social links menu.
+ * Displays SVG icons in social links menu.
  *
  * @param string   $item_output The menu item's starting HTML output.
  * @param WP_Post  $item        Menu item data object.
@@ -141,7 +141,7 @@ function twentyseventeen_nav_menu_social_icons( $item_output, $item, $depth, $ar
 add_filter( 'walker_nav_menu_start_el', 'twentyseventeen_nav_menu_social_icons', 10, 4 );
 
 /**
- * Add dropdown icon if menu item has children.
+ * Adds dropdown icon if menu item has children.
  *
  * @param string   $title The menu item's title.
  * @param WP_Post  $item  The current menu item.