HTML API: Document shorthand usage of the next_tag().

Documents the shorthand usage, i.e. `$this->next_tag( 'img' )`, of `WP_HTML_Tag_Processor::next_tag()`. Also includes table alignments and formatting adjustments in the class docs. Follow-up to [55203], [55206]. Props zieladam, poena, dmsnell, costdev, hellofromTonya. Fixes #57863. See #57575. git-svn-id: https://develop.svn.wordpress.org/trunk@55477 602fd350-edb4-49c9-b593-d223f7449a82
AKJUS · Mar 7, 2023 · 7fd029c · 7fd029c
1 parent 961661a
commit 7fd029c
Showing 1 changed file with 9 additions and 8 deletions.
diff --git a/src/wp-includes/html-api/class-wp-html-tag-processor.php b/src/wp-includes/html-api/class-wp-html-tag-processor.php
@@ -40,7 +40,7 @@
  * Example:
  * ```php
  *     $tags = new WP_HTML_Tag_Processor( $html );
- *     if ( $tags->next_tag( array( 'tag_name' => 'option' ) ) ) {
+ *     if ( $tags->next_tag( 'option' ) ) {
  *         $tags->set_attribute( 'selected', true );
  *     }
  * ```
@@ -58,10 +58,11 @@
  *     $tags->next_tag();
  * ```
  *
- * | Goal                                                      | Query                                                                      |
- * |-----------------------------------------------------------|----------------------------------------------------------------------------|
- * | Find any tag.                                             | `$tags->next_tag();`                                                       |
+ * | Goal                                                      | Query                                                                           |
+ * |-----------------------------------------------------------|---------------------------------------------------------------------------------|
+ * | Find any tag.                                             | `$tags->next_tag();`                                                            |
  * | Find next image tag.                                      | `$tags->next_tag( array( 'tag_name' => 'img' ) );`                              |
+ * | Find next image tag (without passing the array).          | `$tags->next_tag( 'img' );`                                                     |
  * | Find next tag containing the `fullwidth` CSS class.       | `$tags->next_tag( array( 'class_name' => 'fullwidth' ) );`                      |
  * | Find next image tag containing the `fullwidth` CSS class. | `$tags->next_tag( array( 'tag_name' => 'img', 'class_name' => 'fullwidth' ) );` |
  *
@@ -1610,7 +1611,7 @@ private function get_enqueued_attribute_value( $comparable_name ) {
 	 *     $p->get_attribute( 'enabled' ) === true;
 	 *     $p->get_attribute( 'aria-label' ) === null;
 	 *
-	 *     $p->next_tag( array() ) === false;
+	 *     $p->next_tag() === false;
 	 *     $p->get_attribute( 'class' ) === null;
 	 * ```
 	 *
@@ -1691,7 +1692,7 @@ public function get_attribute( $name ) {
 	 *     $p->next_tag( array( 'class_name' => 'test' ) ) === true;
 	 *     $p->get_attribute_names_with_prefix( 'data-' ) === array( 'data-enabled', 'data-test-id' );
 	 *
-	 *     $p->next_tag( array() ) === false;
+	 *     $p->next_tag() === false;
 	 *     $p->get_attribute_names_with_prefix( 'data-' ) === null;
 	 * ```
 	 *
@@ -1722,10 +1723,10 @@ function get_attribute_names_with_prefix( $prefix ) {
 	 * Example:
 	 * ```php
 	 *     $p = new WP_HTML_Tag_Processor( '<DIV CLASS="test">Test</DIV>' );
-	 *     $p->next_tag( array() ) === true;
+	 *     $p->next_tag() === true;
 	 *     $p->get_tag() === 'DIV';
 	 *
-	 *     $p->next_tag( array() ) === false;
+	 *     $p->next_tag() === false;
 	 *     $p->get_tag() === null;
 	 * ```
 	 *