Twenty Twenty-One: Add missing documentation for some filters.

Add missing `@since` tags for some functions.

Follow-up to [49216], [49220], [49854], [51294].

See #52628, #53461.
Built from https://develop.svn.wordpress.org/trunk@51304


git-svn-id: http://core.svn.wordpress.org/trunk@50913 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-content/themes/twentytwentyone/assets/js/customize-helpers.js

@@ -1,6 +1,8 @@
 /**
  * Get luminance from a HEX color.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param {string} hex - The hex color.
  *
  * @return {number} - Returns the luminance, number between 0 and 255.
@@ -13,6 +15,8 @@ function twentytwentyoneGetHexLum( hex ) { // jshint ignore:line
 /**
  * Get RGB from HEX.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param {string} hex - The hex color.
  *
  * @return {Object} - Returns an object {r, g, b}

wp-content/themes/twentytwentyone/assets/js/palette-colorpicker.js

@@ -5,6 +5,8 @@
  * with a few tweaks:
  * 		Removed the hue picker script because we don't use it here
  * 		Added the "palettes" argument in wpColorPicker().
+ *
+ * @since Twenty Twenty-One 1.0
  */
 wp.customize.controlConstructor['twenty-twenty-one-color'] = wp.customize.Control.extend( {
 	ready: function() {

wp-content/themes/twentytwentyone/assets/js/polyfills.js

@@ -7,6 +7,8 @@
 /**
  * Polyfill for Element.closest() because we need to support IE11.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/closest
  */
 if ( ! Element.prototype.matches ) {
@@ -29,6 +31,8 @@ if ( ! Element.prototype.closest ) {
 /**
  * Polyfill for NodeList.foreach() because we need to support IE11.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/NodeList/forEach
  */
 if ( window.NodeList && ! NodeList.prototype.forEach ) {

wp-content/themes/twentytwentyone/assets/js/primary-navigation.js

@@ -7,9 +7,10 @@
 /**
  * Toggle an attribute's value
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param {Element} el - The element.
  * @param {boolean} withListeners - Whether we want to add/remove listeners or not.
- * @since Twenty Twenty-One 1.0
  */
 function twentytwentyoneToggleAriaExpanded( el, withListeners ) {
 	if ( 'true' !== el.getAttribute( 'aria-expanded' ) ) {
@@ -37,6 +38,8 @@ function twentytwentyoneCollapseMenuOnClickOutside( event ) {
 /**
  * Changes the position of submenus so they always fit the screen horizontally.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param {Element} li - The li element.
  */
 function twentytwentyoneSubmenuPosition( li ) {
@@ -65,6 +68,8 @@ function twentytwentyoneSubmenuPosition( li ) {
 /**
  * Handle clicks on submenu toggles.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param {Element} el - The element.
  */
 function twentytwentyoneExpandSubMenu( el ) { // jshint ignore:line
@@ -92,6 +97,8 @@ function twentytwentyoneExpandSubMenu( el ) { // jshint ignore:line
 	/**
 	 * Menu Toggle Behaviors
 	 *
+	 * @since Twenty Twenty-One 1.0
+	 *
 	 * @param {string} id - The ID.
 	 */
 	var navMenu = function( id ) {
@@ -112,9 +119,12 @@ function twentytwentyoneExpandSubMenu( el ) { // jshint ignore:line
 				mobileButton.focus();
 			};
 		}
+
 		/**
 		 * Trap keyboard navigation in the menu modal.
-		 * Adapted from TwentyTwenty
+		 * Adapted from Twenty Twenty.
+		 *
+		 * @since Twenty Twenty-One 1.0
 		 */
 		document.addEventListener( 'keydown', function( event ) {
 			var modal, elements, selectors, lastEl, firstEl, activeEl, tabKey, shiftKey, escKey;
@@ -158,7 +168,9 @@ function twentytwentyoneExpandSubMenu( el ) { // jshint ignore:line
 
 		/**
 		 * Close menu and scroll to anchor when an anchor link is clicked.
-		 * Adapted from TwentyTwenty.
+		 * Adapted from Twenty Twenty.
+		 *
+		 * @since Twenty Twenty-One 1.1
 		 */
 		document.addEventListener( 'click', function( event ) {
 			// If target onclick is <a> with # within the href attribute

wp-content/themes/twentytwentyone/assets/js/skip-link-focus-fix.js

@@ -6,6 +6,8 @@
  * This is the source file for what is minified in the twenty_twenty_one_skip_link_focus_fix() PHP function.
  *
  * Learn more: https://git.io/vWdr2
+ *
+ * @since Twenty Twenty-One 1.0
  */
 ( function() {
 	var isIe = /(trident|msie)/i.test( navigator.userAgent );

wp-content/themes/twentytwentyone/functions.php

@@ -95,7 +95,7 @@ if ( ! function_exists( 'twenty_twenty_one_setup' ) ) {
 			)
 		);
 
-		/**
+		/*
 		 * Add support for core custom logo.
 		 *
 		 * @link https://codex.wordpress.org/Theme_Logo
@@ -485,6 +485,8 @@ add_action( 'enqueue_block_editor_assets', 'twentytwentyone_block_editor_script'
  * 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.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @link https://git.io/vWdr2
  */
 function twenty_twenty_one_skip_link_focus_fix() {
@@ -603,6 +605,13 @@ add_action( 'customize_controls_enqueue_scripts', 'twentytwentyone_customize_con
  * @return void
  */
 function twentytwentyone_the_html_classes() {
+	/**
+	 * Filters the classes for the main <html> element.
+	 *
+	 * @since Twenty Twenty-One 1.0
+	 *
+	 * @param string The list of classes. Default empty string.
+	 */
 	$classes = apply_filters( 'twentytwentyone_html_classes', '' );
 	if ( ! $classes ) {
 		return;

wp-content/themes/twentytwentyone/image.php

@@ -24,7 +24,9 @@ while ( have_posts() ) {
 				/**
 				 * Filter the default image attachment size.
 				 *
-				 * @param string $image_size Image size. Default 'large'.
+				 * @since Twenty Twenty-One 1.0
+				 *
+				 * @param string $image_size Image size. Default 'full'.
 				 */
 				$image_size = apply_filters( 'twenty_twenty_one_attachment_size', 'full' );
 				echo wp_get_attachment_image( get_the_ID(), $image_size );

wp-content/themes/twentytwentyone/inc/menu-functions.php

@@ -54,6 +54,8 @@ function twenty_twenty_one_get_social_link_svg( $uri, $size = 24 ) {
 /**
  * Displays SVG icons in the footer navigation.
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param string   $item_output The menu item's starting HTML output.
  * @param WP_Post  $item        Menu item data object.
  * @param int      $depth       Depth of the menu. Used for padding.

wp-content/themes/twentytwentyone/inc/template-functions.php

@@ -103,6 +103,13 @@ add_filter( 'comment_form_defaults', 'twenty_twenty_one_comment_form_defaults' )
  * @return bool
  */
 function twenty_twenty_one_can_show_post_thumbnail() {
+	/**
+	 * Filters whether post thumbnail can be displayed.
+	 *
+	 * @since Twenty Twenty-One 1.0
+	 *
+	 * @param bool $show_post_thumbnail Whether to show post thumbnail.
+	 */
 	return apply_filters(
 		'twenty_twenty_one_can_show_post_thumbnail',
 		! post_password_required() && ! is_attachment() && has_post_thumbnail()
@@ -121,7 +128,9 @@ function twenty_twenty_one_get_avatar_size() {
 }
 
 /**
- * Creates continue reading text
+ * Creates continue reading text.
+ *
+ * @since Twenty Twenty-One 1.0
  */
 function twenty_twenty_one_continue_reading_text() {
 	$continue_reading = sprintf(
@@ -134,7 +143,9 @@ function twenty_twenty_one_continue_reading_text() {
 }
 
 /**
- * Create the continue reading link for excerpt.
+ * Creates the continue reading link for excerpt.
+ *
+ * @since Twenty Twenty-One 1.0
  */
 function twenty_twenty_one_continue_reading_link_excerpt() {
 	if ( ! is_admin() ) {
@@ -146,7 +157,9 @@ function twenty_twenty_one_continue_reading_link_excerpt() {
 add_filter( 'excerpt_more', 'twenty_twenty_one_continue_reading_link_excerpt' );
 
 /**
- * Create the continue reading link.
+ * Creates the continue reading link.
+ *
+ * @since Twenty Twenty-One 1.0
  */
 function twenty_twenty_one_continue_reading_link() {
 	if ( ! is_admin() ) {
@@ -159,7 +172,7 @@ add_filter( 'the_content_more_link', 'twenty_twenty_one_continue_reading_link' )
 
 if ( ! function_exists( 'twenty_twenty_one_post_title' ) ) {
 	/**
-	 * Add a title to posts and pages that are missing titles.
+	 * Adds a title to posts and pages that are missing titles.
 	 *
 	 * @since Twenty Twenty-One 1.0
 	 *
@@ -189,6 +202,8 @@ function twenty_twenty_one_get_icon_svg( $group, $icon, $size = 24 ) {
 /**
  * Changes the default navigation arrows to svg icons
  *
+ * @since Twenty Twenty-One 1.0
+ *
  * @param string $calendar_output The generated HTML of the calendar.
  * @return string
  */
@@ -204,7 +219,9 @@ add_filter( 'get_calendar', 'twenty_twenty_one_change_calendar_nav_arrows' );
  *
  * Return CSS for non-latin language, if available, or null
  *
- * @param string $type Whether to return CSS for the "front-end", "block-editor" or "classic-editor".
+ * @since Twenty Twenty-One 1.0
+ *
+ * @param string $type Whether to return CSS for the "front-end", "block-editor", or "classic-editor".
  * @return string
  */
 function twenty_twenty_one_get_non_latin_css( $type = 'front-end' ) {
@@ -212,7 +229,13 @@ function twenty_twenty_one_get_non_latin_css( $type = 'front-end' ) {
 	// Fetch site locale.
 	$locale = get_bloginfo( 'language' );
 
-	// Define fallback fonts for non-latin languages.
+	/**
+	 * Filters the fallback fonts for non-latin languages.
+	 *
+	 * @since Twenty Twenty-One 1.0
+	 *
+	 * @param array $font_family An array of locales and font families.
+	 */
 	$font_family = apply_filters(
 		'twenty_twenty_one_get_localized_font_family_types',
 		array(
@@ -282,7 +305,13 @@ function twenty_twenty_one_get_non_latin_css( $type = 'front-end' ) {
 		return '';
 	}
 
-	// Define elements to apply fallback fonts to.
+	/**
+	 * Filters the elements to apply fallback fonts to.
+	 *
+	 * @since Twenty Twenty-One 1.0
+	 *
+	 * @param array $elements An array of elements for "front-end", "block-editor", or "classic-editor".
+	 */
 	$elements = apply_filters(
 		'twenty_twenty_one_get_localized_font_family_elements',
 		array(
@@ -368,6 +397,7 @@ function twenty_twenty_one_print_first_instance_of_block( $block_name, $content
 	}
 
 	if ( $blocks_content ) {
+		/** This filter is documented in wp-includes/post-template.php */
 		echo apply_filters( 'the_content', $blocks_content ); // phpcs:ignore WordPress.Security.EscapeOutput
 		return true;
 	}

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-alpha-51303';
+$wp_version = '5.9-alpha-51304';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.