Enforce @SInCE tags in /packages/block-serialization-default-parser/ …

…and other files (#60007)

1. Added support for checking `@since` tags for class, trait, interface, and enum declarations.
2. Added support for checking `@since` tags for class and trait properties;
3. Added support for checking `@since` tags for class, interface, and trait method declarations;
4. Added support for checking `@since` tags for WordPress functions that invoke hooks: `do_action()`, `do_action_ref_array()`, `apply_filters()`, `apply_filters_ref_array()`.
5. Refactored unit tests; duplicate code moved to the new `GutenbergCS\Gutenberg\Tests\AbstractSniffUnitTest` class.

Co-authored-by: anton-vlasenko <antonvlasenko@git.wordpress.org>
Co-authored-by: rodrigoprimo <rodrigosprimo@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>

packages/block-library/src/latest-posts/index.php

@@ -152,6 +152,7 @@ function render_block_core_latest_posts( $attributes ) {
 			 * […] is the default excerpt ending from wp_trim_excerpt() in Core.
 			 */
 			if ( str_ends_with( $trimmed_excerpt, ' […]' ) ) {
+				/** This filter is documented in wp-includes/formatting.php */
 				$excerpt_length = (int) apply_filters( 'excerpt_length', $block_core_latest_posts_excerpt_length );
 				if ( $excerpt_length <= $block_core_latest_posts_excerpt_length ) {
 					$trimmed_excerpt  = substr( $trimmed_excerpt, 0, -11 );

packages/block-library/src/navigation/index.php

@@ -7,17 +7,23 @@
 
 /**
  * Helper functions used to render the navigation block.
+ *
+ * @since 6.5.0
  */
 class WP_Navigation_Block_Renderer {
 
 	/**
 	 * Used to determine whether or not a navigation has submenus.
+	 *
+	 * @since 6.5.0
 	 */
 	private static $has_submenus = false;
 
 	/**
 	 * Used to determine which blocks need an <li> wrapper.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @var array
 	 */
 	private static $needs_list_item_wrapper = array(
@@ -29,13 +35,17 @@ class WP_Navigation_Block_Renderer {
 	/**
 	 * Keeps track of all the navigation names that have been seen.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @var array
 	 */
 	private static $seen_menu_names = array();
 
 	/**
 	 * Returns whether or not this is responsive navigation.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return bool Returns whether or not this is responsive navigation.
 	 */
@@ -51,6 +61,8 @@ private static function is_responsive( $attributes ) {
 	/**
 	 * Returns whether or not a navigation has a submenu.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param WP_Block_List $inner_blocks The list of inner blocks.
 	 * @return bool Returns whether or not a navigation has a submenu and also sets the member variable.
 	 */
@@ -88,6 +100,8 @@ private static function has_submenus( $inner_blocks ) {
 	/**
 	 * Determine whether the navigation blocks is interactive.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array         $attributes   The block attributes.
 	 * @param WP_Block_List $inner_blocks The list of inner blocks.
 	 * @return bool Returns whether or not to load the view script.
@@ -101,6 +115,8 @@ private static function is_interactive( $attributes, $inner_blocks ) {
 	/**
 	 * Returns whether or not a block needs a list item wrapper.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param WP_Block $block The block.
 	 * @return bool Returns whether or not a block needs a list item wrapper.
 	 */
@@ -127,6 +143,8 @@ private static function does_block_need_a_list_item_wrapper( $block ) {
 	/**
 	 * Returns the markup for a single inner block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param WP_Block $inner_block The inner block.
 	 * @return string Returns the markup for a single inner block.
 	 */
@@ -144,6 +162,8 @@ private static function get_markup_for_inner_block( $inner_block ) {
 	/**
 	 * Returns the html for the inner blocks of the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array         $attributes   The block attributes.
 	 * @param WP_Block_List $inner_blocks The list of inner blocks.
 	 * @return string Returns the html for the inner blocks of the navigation block.
@@ -201,6 +221,8 @@ private static function get_inner_blocks_html( $attributes, $inner_blocks ) {
 	/**
 	 * Gets the inner blocks for the navigation block from the navigation post.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return WP_Block_List Returns the inner blocks for the navigation block.
 	 */
@@ -236,6 +258,8 @@ private static function get_inner_blocks_from_navigation_post( $attributes ) {
 	/**
 	 * Gets the inner blocks for the navigation block from the fallback.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return WP_Block_List Returns the inner blocks for the navigation block.
 	 */
@@ -253,6 +277,8 @@ private static function get_inner_blocks_from_fallback( $attributes ) {
 	/**
 	 * Gets the inner blocks for the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array    $attributes The block attributes.
 	 * @param WP_Block $block The parsed block.
 	 * @return WP_Block_List Returns the inner blocks for the navigation block.
@@ -311,6 +337,8 @@ private static function get_inner_blocks( $attributes, $block ) {
 	/**
 	 * Gets the name of the current navigation, if it has one.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return string Returns the name of the navigation.
 	 */
@@ -346,6 +374,8 @@ private static function get_navigation_name( $attributes ) {
 	/**
 	 * Returns the layout class for the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return string Returns the layout class for the navigation block.
 	 */
@@ -377,6 +407,8 @@ private static function get_layout_class( $attributes ) {
 	/**
 	 * Return classes for the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return string Returns the classes for the navigation block.
 	 */
@@ -404,6 +436,8 @@ private static function get_classes( $attributes ) {
 	/**
 	 * Get styles for the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return string Returns the styles for the navigation block.
 	 */
@@ -417,6 +451,8 @@ private static function get_styles( $attributes ) {
 	/**
 	 * Get the responsive container markup
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array         $attributes The block attributes.
 	 * @param WP_Block_List $inner_blocks The list of inner blocks.
 	 * @param string        $inner_blocks_html The markup for the inner blocks.
@@ -515,6 +551,8 @@ private static function get_responsive_container_markup( $attributes, $inner_blo
 	/**
 	 * Get the wrapper attributes
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array         $attributes    The block attributes.
 	 * @param WP_Block_List $inner_blocks  A list of inner blocks.
 	 * @return string Returns the navigation block markup.
@@ -544,6 +582,8 @@ private static function get_nav_wrapper_attributes( $attributes, $inner_blocks )
 	/**
 	 * Gets the nav element directives.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param bool $is_interactive Whether the block is interactive.
 	 * @return string the directives for the navigation element.
 	 */
@@ -574,6 +614,8 @@ private static function get_nav_element_directives( $is_interactive ) {
 	/**
 	 * Handle view script module loading.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array         $attributes   The block attributes.
 	 * @param WP_Block      $block        The parsed block.
 	 * @param WP_Block_List $inner_blocks The list of inner blocks.
@@ -598,6 +640,8 @@ private static function handle_view_script_module_loading( $attributes, $block,
 	/**
 	 * Returns the markup for the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array         $attributes The block attributes.
 	 * @param WP_Block_List $inner_blocks The list of inner blocks.
 	 * @return string Returns the navigation wrapper markup.
@@ -613,6 +657,8 @@ private static function get_wrapper_markup( $attributes, $inner_blocks ) {
 	/**
 	 * Returns a unique name for the navigation.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array $attributes The block attributes.
 	 * @return string Returns a unique name for the navigation.
 	 */
@@ -632,6 +678,8 @@ private static function get_unique_navigation_name( $attributes ) {
 	/**
 	 * Renders the navigation block.
 	 *
+	 * @since 6.5.0
+	 *
 	 * @param array    $attributes The block attributes.
 	 * @param string   $content    The saved content.
 	 * @param WP_Block $block      The parsed block.
@@ -1604,7 +1652,9 @@ function block_core_navigation_insert_hooked_blocks_into_rest_response( $respons
 	// Remove mock Navigation block wrapper.
 	$content = block_core_navigation_remove_serialized_parent_block( $content );
 
-	$response->data['content']['raw']      = $content;
+	$response->data['content']['raw'] = $content;
+
+	/** This filter is documented in wp-includes/post-template.php */
 	$response->data['content']['rendered'] = apply_filters( 'the_content', $content );
 
 	return $response;

packages/widgets/src/blocks/legacy-widget/index.php

@@ -8,6 +8,8 @@
 /**
  * Renders the 'core/legacy-widget' block.
  *
+ * @since 5.8.0
+ *
  * @global int $wp_widget_factory.
  *
  * @param array $attributes The block attributes.
@@ -56,6 +58,8 @@ function render_block_core_legacy_widget( $attributes ) {
 
 /**
  * Registers the 'core/legacy-widget' block.
+ *
+ * @since 5.8.0
  */
 function register_block_core_legacy_widget() {
 	register_block_type_from_metadata(
@@ -72,6 +76,8 @@ function register_block_core_legacy_widget() {
  * Intercepts any request with legacy-widget-preview in the query param and, if
  * set, renders a page containing a preview of the requested Legacy Widget
  * block.
+ *
+ * @since 5.8.0
  */
 function handle_legacy_widget_preview_iframe() {
 	if ( empty( $_GET['legacy-widget-preview'] ) ) {

packages/widgets/src/blocks/widget-group/index.php

@@ -8,6 +8,8 @@
 /**
  * Renders the 'core/widget-group' block.
  *
+ * @since 5.9.0
+ *
  * @global array      $wp_registered_sidebars
  * @global int|string $_sidebar_being_rendered
  *
@@ -45,6 +47,8 @@ function render_block_core_widget_group( $attributes, $content, $block ) {
 
 /**
  * Registers the 'core/widget-group' block.
+ *
+ * @since 5.9.0
  */
 function register_block_core_widget_group() {
 	register_block_type_from_metadata(
@@ -62,6 +66,8 @@ function register_block_core_widget_group() {
  * it. This lets us get to the current sidebar in
  * render_block_core_widget_group().
  *
+ * @since 5.9.0
+ *
  * @global int|string $_sidebar_being_rendered
  *
  * @param int|string $index       Index, name, or ID of the dynamic sidebar.
@@ -76,6 +82,8 @@ function note_sidebar_being_rendered( $index ) {
  * Clear whatever we set in note_sidebar_being_rendered() after WordPress
  * finishes rendering a sidebar.
  *
+ * @since 5.9.0
+ *
  * @global int|string $_sidebar_being_rendered
  */
 function discard_sidebar_being_rendered() {

phpcs.xml.dist

@@ -172,8 +172,11 @@
 			</property>
 		</properties>
 	</rule>
-	<rule ref="Gutenberg.Commenting.FunctionCommentSinceTag">
+	<rule ref="Gutenberg.Commenting.SinceTag">
 		<!-- The sniff ensures that functions have a valid @since tag but skips checking experimental blocks. -->
 		<include-pattern>/packages/block-library/src/.+/*\.php$</include-pattern>
+		<include-pattern>/packages/block-serialization-default-parser/.+/*\.php$</include-pattern>
+		<include-pattern>/packages/widgets/src/blocks/legacy-widget/index\.php$</include-pattern>
+		<include-pattern>/packages/widgets/src/blocks/widget-group/index\.php$</include-pattern>
 	</rule>
 </ruleset>