From 7d725158996f16d358ea3bad82acb2d1f86eda5c Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 2 Jul 2021 08:56:06 +0000 Subject: [PATCH] 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. git-svn-id: https://develop.svn.wordpress.org/trunk@51304 602fd350-edb4-49c9-b593-d223f7449a82 --- .../assets/js/customize-helpers.js | 4 ++ .../assets/js/palette-colorpicker.js | 2 + .../twentytwentyone/assets/js/polyfills.js | 4 ++ .../assets/js/primary-navigation.js | 18 ++++++-- .../assets/js/skip-link-focus-fix.js | 2 + .../themes/twentytwentyone/functions.php | 11 ++++- .../themes/twentytwentyone/image.php | 4 +- .../twentytwentyone/inc/menu-functions.php | 2 + .../inc/template-functions.php | 44 ++++++++++++++++--- 9 files changed, 79 insertions(+), 12 deletions(-) diff --git a/src/wp-content/themes/twentytwentyone/assets/js/customize-helpers.js b/src/wp-content/themes/twentytwentyone/assets/js/customize-helpers.js index 6523860a87..6678c3d9d9 100644 --- a/src/wp-content/themes/twentytwentyone/assets/js/customize-helpers.js +++ b/src/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} diff --git a/src/wp-content/themes/twentytwentyone/assets/js/palette-colorpicker.js b/src/wp-content/themes/twentytwentyone/assets/js/palette-colorpicker.js index 89271f336b..ced9e02af9 100644 --- a/src/wp-content/themes/twentytwentyone/assets/js/palette-colorpicker.js +++ b/src/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() { diff --git a/src/wp-content/themes/twentytwentyone/assets/js/polyfills.js b/src/wp-content/themes/twentytwentyone/assets/js/polyfills.js index 8c3a5cf9ea..f2692d8c34 100644 --- a/src/wp-content/themes/twentytwentyone/assets/js/polyfills.js +++ b/src/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 ) { diff --git a/src/wp-content/themes/twentytwentyone/assets/js/primary-navigation.js b/src/wp-content/themes/twentytwentyone/assets/js/primary-navigation.js index af9c6df128..4c88190f12 100644 --- a/src/wp-content/themes/twentytwentyone/assets/js/primary-navigation.js +++ b/src/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 with # within the href attribute diff --git a/src/wp-content/themes/twentytwentyone/assets/js/skip-link-focus-fix.js b/src/wp-content/themes/twentytwentyone/assets/js/skip-link-focus-fix.js index ed4676e6c3..5ae1338dc8 100644 --- a/src/wp-content/themes/twentytwentyone/assets/js/skip-link-focus-fix.js +++ b/src/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 ); diff --git a/src/wp-content/themes/twentytwentyone/functions.php b/src/wp-content/themes/twentytwentyone/functions.php index 1139c3b659..7d9b767d0e 100644 --- a/src/wp-content/themes/twentytwentyone/functions.php +++ b/src/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 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; diff --git a/src/wp-content/themes/twentytwentyone/image.php b/src/wp-content/themes/twentytwentyone/image.php index 66d3a6e85c..4ab5e8ce58 100644 --- a/src/wp-content/themes/twentytwentyone/image.php +++ b/src/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 ); diff --git a/src/wp-content/themes/twentytwentyone/inc/menu-functions.php b/src/wp-content/themes/twentytwentyone/inc/menu-functions.php index 28f21cd5b9..0299c58c41 100644 --- a/src/wp-content/themes/twentytwentyone/inc/menu-functions.php +++ b/src/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. diff --git a/src/wp-content/themes/twentytwentyone/inc/template-functions.php b/src/wp-content/themes/twentytwentyone/inc/template-functions.php index d21da59d21..1e61ba3054 100644 --- a/src/wp-content/themes/twentytwentyone/inc/template-functions.php +++ b/src/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; }