From c87a1d6e2eadefe10f49019f71cc2b1fc3f84dcd Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Tue, 1 Nov 2022 20:15:25 +0000
Subject: [PATCH] Docs: Update comments in `wp_nav_menu()` tests per the
 documentation standards.

Includes:
* Fixing a few typos.
* Using the correct format for multi-line comments.
* Removing some comments that duplicate the assertion messages without providing any additional context.

Follow-up to [54478].

See #56792.

git-svn-id: https://develop.svn.wordpress.org/trunk@54741 602fd350-edb4-49c9-b593-d223f7449a82
---
 tests/phpunit/tests/menu/wp-nav-menu.php | 40 ++++++++++--------------
 1 file changed, 17 insertions(+), 23 deletions(-)

diff --git a/tests/phpunit/tests/menu/wp-nav-menu.php b/tests/phpunit/tests/menu/wp-nav-menu.php
index ac7c815b89..60a523bfd1 100644
--- a/tests/phpunit/tests/menu/wp-nav-menu.php
+++ b/tests/phpunit/tests/menu/wp-nav-menu.php
@@ -53,12 +53,13 @@ class Tests_Menu_wpNavMenu extends WP_UnitTestCase {
 			)
 		);
 
-		/**
-		 * This filter is used to prevent reusing a menu item ID more that once. It cause the tests to failed
-		 * after the first one since the IDs are missing from the HTML generated by `wp_nav_menu`.
+		/*
+		 * This filter is used to prevent reusing a menu item ID more that once.
+		 * It caused the tests to fail after the first one since the IDs are missing
+		 * from the HTML generated by `wp_nav_menu()`.
 		 *
-		 * To allow the tests to pass, we remove the filter before running them and add it back after
-		 * they ran ({@see Tests_Menu_wpNavMenu::tear_down_after_class()}).
+		 * To allow the tests to pass, we remove the filter before running them
+		 * and add it back after they ran ({@see Tests_Menu_wpNavMenu::tear_down_after_class()}).
 		 */
 		remove_filter( 'nav_menu_item_id', '_nav_menu_item_id_use_once' );
 	}
@@ -66,8 +67,9 @@ class Tests_Menu_wpNavMenu extends WP_UnitTestCase {
 	public static function tear_down_after_class() {
 		wp_delete_nav_menu( self::$menu_id );
 
-		/**
-		 * This filter was removed to let the tests pass and need to be added back ({@see Tests_Menu_wpNavMenu::set_up_before_class}).
+		/*
+		 * This filter was removed to let the tests pass and needs to be added back
+		 * ({@see Tests_Menu_wpNavMenu::set_up_before_class}).
 		 */
 		add_filter( 'nav_menu_item_id', '_nav_menu_item_id_use_once', 10, 2 );
 
@@ -75,8 +77,8 @@ class Tests_Menu_wpNavMenu extends WP_UnitTestCase {
 	}
 
 	/**
-	 * Test all menu items containing children have the CSS class `menu-item-has-children` when displaying the menu
-	 * without specifying a custom depth.
+	 * Tests that all menu items containing children have the CSS class `menu-item-has-children`
+	 * when displaying the menu without specifying a custom depth.
 	 *
 	 * @ticket 28620
 	 */
@@ -90,35 +92,31 @@ class Tests_Menu_wpNavMenu extends WP_UnitTestCase {
 			)
 		);
 
-		// Level 0 should be present in the HTML output and have the `menu-item-has-children` class.
 		$this->assertStringContainsString(
 			sprintf(
 				'<li id="menu-item-%1$d" class="menu-item menu-item-type-custom menu-item-object-custom menu-item-has-children menu-item-%1$d">',
 				self::$lvl0_menu_item
 			),
 			$menu_html,
-			'Level 0 should be present in the HTML output and have the menu-item-has-children class'
+			'Level 0 should be present in the HTML output and have the `menu-item-has-children` class.'
 		);
 
-		// Level 1 should be present in the HTML output and have the `menu-item-has-children` class.
 		$this->assertStringContainsString(
 			sprintf(
 				'<li id="menu-item-%1$d" class="menu-item menu-item-type-custom menu-item-object-custom menu-item-has-children menu-item-%1$d">',
 				self::$lvl1_menu_item
 			),
 			$menu_html,
-			'Level 1 should be present in the HTML output and have the menu-item-has-children class'
+			'Level 1 should be present in the HTML output and have the `menu-item-has-children` class.'
 		);
 
-		// Level 2 should be present in the HTML output and not have the `menu-item-has-children` class since it has no
-		// children.
 		$this->assertStringContainsString(
 			sprintf(
 				'<li id="menu-item-%1$d" class="menu-item menu-item-type-custom menu-item-object-custom menu-item-%1$d">',
 				self::$lvl2_menu_item
 			),
 			$menu_html,
-			'Level 2 should be present in the HTML output and not have the `menu-item-has-children` class since it has no children'
+			'Level 2 should be present in the HTML output and not have the `menu-item-has-children` class since it has no children.'
 		);
 	}
 
@@ -139,35 +137,31 @@ class Tests_Menu_wpNavMenu extends WP_UnitTestCase {
 			)
 		);
 
-		// Level 0 should be present in the HTML output and have the `menu-item-has-children` class.
 		$this->assertStringContainsString(
 			sprintf(
 				'<li id="menu-item-%1$d" class="menu-item menu-item-type-custom menu-item-object-custom menu-item-has-children menu-item-%1$d">',
 				self::$lvl0_menu_item
 			),
 			$menu_html,
-			'Level 0 should be present in the HTML output and have the menu-item-has-children class'
+			'Level 0 should be present in the HTML output and have the `menu-item-has-children` class.'
 		);
 
-		// Level 1 should be present in the HTML output and not have the `menu-item-has-children` class since its the
-		// last item to be rendered.
 		$this->assertStringContainsString(
 			sprintf(
 				'<li id="menu-item-%1$d" class="menu-item menu-item-type-custom menu-item-object-custom menu-item-%1$d">',
 				self::$lvl1_menu_item
 			),
 			$menu_html,
-			'Level 1 should be present in the HTML output and not have the `menu-item-has-children` class since its the last item to be rendered'
+			'Level 1 should be present in the HTML output and not have the `menu-item-has-children` class since it is the last item to be rendered.'
 		);
 
-		// Level 2 should not be present in the HTML output.
 		$this->assertStringNotContainsString(
 			sprintf(
 				'<li id="menu-item-%d"',
 				self::$lvl2_menu_item
 			),
 			$menu_html,
-			'Level 2 should not be present in the HTML output'
+			'Level 2 should not be present in the HTML output.'
 		);
 	}
 }