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

Author: SergeyBiryukov

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

@@ -190,7 +190,7 @@ function wp_get_list_item_separator() {
 endif;
 
 /**
- * Register widget area.
+ * Registers widget area.
  *
  * @link https://developer.wordpress.org/themes/functionality/sidebars/#registering-a-sidebar
  */
@@ -235,7 +235,7 @@ function twentynineteen_excerpt_more( $link ) {
 add_filter( 'excerpt_more', 'twentynineteen_excerpt_more' );
 
 /**
- * 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.
  *
@@ -291,7 +291,7 @@ function twentynineteen_scripts() {
 add_action( 'wp_enqueue_scripts', 'twentynineteen_scripts' );
 
 /**
- * Fix skip link focus in IE11.
+ * Fixes skip link focus in IE11.
  *
  * This does not enqueue the script because it is tiny and because it is only for IE11,
  * thus it does not warrant having an entire dedicated blocking script being loaded.
@@ -311,7 +311,7 @@ function twentynineteen_skip_link_focus_fix() {
 }
 
 /**
- * Enqueue supplemental block editor styles.
+ * Enqueues supplemental block editor styles.
  */
 function twentynineteen_editor_customizer_styles() {
 
@@ -326,7 +326,7 @@ function twentynineteen_editor_customizer_styles() {
 add_action( 'enqueue_block_editor_assets', 'twentynineteen_editor_customizer_styles' );
 
 /**
- * Display custom color CSS in customizer and on frontend.
+ * Displays custom color CSS in customizer and on frontend.
  */
 function twentynineteen_colors_css_wrap() {
 
@@ -386,7 +386,7 @@ function twentynineteen_colors_css_wrap() {
 require get_template_directory() . '/inc/customizer.php';
 
 /**
- * Register block patterns and pattern categories.
+ * Registers block patterns and pattern categories.
  *
  * @since Twenty Nineteen 3.0
  */

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

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

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

@@ -8,7 +8,7 @@
  */
 
 /**
- * Generate the CSS for the current primary color.
+ * Generates the CSS for the current primary color.
  */
 function twentynineteen_custom_colors_css() {
 

src/wp-content/themes/twentynineteen/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.
  */
@@ -105,7 +105,7 @@ function twentynineteen_customize_register( $wp_customize ) {
 add_action( 'customize_register', 'twentynineteen_customize_register' );
 
 /**
- * Render the site title for the selective refresh partial.
+ * Renders the site title for the selective refresh partial.
  *
  * @return void
  */
@@ -114,7 +114,7 @@ function twentynineteen_customize_partial_blogname() {
 }
 
 /**
- * Render the site tagline for the selective refresh partial.
+ * Renders the site tagline for the selective refresh partial.
  *
  * @return void
  */
@@ -123,23 +123,23 @@ function twentynineteen_customize_partial_blogdescription() {
 }
 
 /**
- * Bind JS handlers to instantly live-preview changes.
+ * Binds JS handlers to instantly live-preview changes.
  */
 function twentynineteen_customize_preview_js() {
 	wp_enqueue_script( 'twentynineteen-customize-preview', get_theme_file_uri( '/js/customize-preview.js' ), array( 'customize-preview' ), '20181214', array( 'in_footer' => true ) );
 }
 add_action( 'customize_preview_init', 'twentynineteen_customize_preview_js' );
 
 /**
- * Load dynamic logic for the customizer controls area.
+ * Loads dynamic logic for the customizer controls area.
  */
 function twentynineteen_panels_js() {
 	wp_enqueue_script( 'twentynineteen-customize-controls', get_theme_file_uri( '/js/customize-controls.js' ), array(), '20181214', array( 'in_footer' => true ) );
 }
 add_action( 'customize_controls_enqueue_scripts', 'twentynineteen_panels_js' );
 
 /**
- * Sanitize custom color choice.
+ * Sanitizes custom color choice.
  *
  * @param string $choice Whether image filter is active.
  * @return string

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

@@ -38,7 +38,7 @@ function twentynineteen_get_social_link_svg( $uri, $size = 24 ) {
 }
 
 /**
- * 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.
@@ -61,7 +61,7 @@ function twentynineteen_nav_menu_social_icons( $item_output, $item, $depth, $arg
 add_filter( 'walker_nav_menu_start_el', 'twentynineteen_nav_menu_social_icons', 10, 4 );
 
 /**
- * Add a dropdown icon to top-level menu items.
+ * Adds a dropdown icon to top-level menu items.
  *
  * @param string   $item_output The menu item's starting HTML output.
  * @param WP_Post  $item        Menu item data object.

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

@@ -202,7 +202,7 @@ function twentynineteen_discussion_avatars_list( $comment_authors ) {
 
 if ( ! function_exists( 'twentynineteen_comment_form' ) ) :
 	/**
-	 * Documentation for function.
+	 * Displays the comment form.
 	 */
 	function twentynineteen_comment_form( $order ) {
 		if ( true === $order || strtolower( $order ) === strtolower( get_option( 'comment_order', 'asc' ) ) ) {
@@ -218,7 +218,7 @@ function twentynineteen_comment_form( $order ) {
 
 if ( ! function_exists( 'twentynineteen_the_posts_navigation' ) ) :
 	/**
-	 * Documentation for function.
+	 * Displays the next and previous posts navigation.
 	 */
 	function twentynineteen_the_posts_navigation() {
 		the_posts_pagination(
@@ -241,7 +241,7 @@ function twentynineteen_the_posts_navigation() {
 
 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/twentynineteen/js/touch-keyboard-navigation.js

@@ -43,7 +43,7 @@
 	}
 
 	/**
-	 * Add class.
+	 * Adds class to an element.
 	 *
 	 * @param {Object} el
 	 * @param {string} cls
@@ -55,7 +55,7 @@
 	}
 
 	/**
-	 * Delete class.
+	 * Deletes class from an element.
 	 *
 	 * @param {Object} el
 	 * @param {string} cls
@@ -65,7 +65,7 @@
 	}
 
 	/**
-	 * Has class?
+	 * Determines whether an element has the given class.
 	 *
 	 * @param {Object} el
 	 * @param {string} cls
@@ -80,7 +80,7 @@
 	}
 
 	/**
-	 * Toggle Aria Expanded state for screenreaders.
+	 * Toggles Aria Expanded state for screenreaders.
 	 *
 	 * @param {Object} ariaItem
 	 */
@@ -99,7 +99,7 @@
 	}
 
 	/**
-	 * Open sub-menu.
+	 * Opens sub-menu.
 	 *
 	 * @param {Object} currentSubMenu
 	 */
@@ -116,7 +116,7 @@
 	}
 
 	/**
-	 * Close sub-menu.
+	 * Closes sub-menu.
 	 *
 	 * @param {Object} currentSubMenu
 	 */
@@ -152,7 +152,7 @@
 	}
 
 	/**
-	 * Find first ancestor of an element by selector.
+	 * Finds first ancestor of an element by selector.
 	 *
 	 * @param {Object} child
 	 * @param {String} selector
@@ -181,7 +181,7 @@
 	}
 
 	/**
-	 * Remove all off-canvas states.
+	 * Removes all off-canvas states.
 	 */
 	function removeAllFocusStates() {
 		'use strict';
@@ -209,7 +209,7 @@
 	}
 
 	/**
-	 * Toggle `focus` class to allow sub-menu access on touch screens.
+	 * Toggles `focus` class to allow sub-menu access on touch screens.
 	 */
 	function toggleSubmenuDisplay() {