From d744c4d39729e2f1df76d93d99560d791ece3043 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Fri, 5 May 2023 12:41:29 +0000
Subject: [PATCH] Docs: Correct the placement of `@see` tags in
 `WP_HTML_Tag_Processor` class.

This moves a reference link in `::get_attribute_names_with_prefix()` below the code example, so that it is correctly displayed in the Developer Resources.

Includes updating some other `@see` tags for consistency as per the documentation standards.

Additionally, the example code for `WP_HTML_Tag_Processor::get_tag()` is updated to show lowercase tag names in the input HTML, so that it does not convey the wrong impression that the uppercase output from `::get_tag()` depends on the case of the input HTML.

Follow-up to [55203].

Props dmsnell, johnbillion, audrasjb, SergeyBiryukov.
Fixes #58254.

git-svn-id: https://develop.svn.wordpress.org/trunk@55724 602fd350-edb4-49c9-b593-d223f7449a82
---
 .../html-api/class-wp-html-tag-processor.php  | 27 +++++++++++--------
 1 file changed, 16 insertions(+), 11 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
index 087bdc72a5..f06302d4b7 100644
--- a/src/wp-includes/html-api/class-wp-html-tag-processor.php
+++ b/src/wp-includes/html-api/class-wp-html-tag-processor.php
@@ -253,9 +253,10 @@ class WP_HTML_Tag_Processor {
 	 * The maximum number of bookmarks allowed to exist at
 	 * any given time.
 	 *
-	 * @see set_bookmark()
 	 * @since 6.2.0
 	 * @var int
+	 *
+	 * @see WP_HTML_Tag_Processor::set_bookmark()
 	 */
 	const MAX_BOOKMARKS = 10;
 
@@ -263,9 +264,10 @@ class WP_HTML_Tag_Processor {
 	 * Maximum number of times seek() can be called.
 	 * Prevents accidental infinite loops.
 	 *
-	 * @see seek()
 	 * @since 6.2.0
 	 * @var int
+	 *
+	 * @see WP_HTML_Tag_Processor::seek()
 	 */
 	const MAX_SEEK_OPS = 1000;
 
@@ -498,9 +500,10 @@ class WP_HTML_Tag_Processor {
 	/**
 	 * Tracks and limits `seek()` calls to prevent accidental infinite loops.
 	 *
-	 * @see seek
 	 * @since 6.2.0
 	 * @var int
+	 *
+	 * @see WP_HTML_Tag_Processor::seek()
 	 */
 	protected $seek_count = 0;
 
@@ -720,9 +723,10 @@ class WP_HTML_Tag_Processor {
 	/**
 	 * Skips contents of title and textarea tags.
 	 *
-	 * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state
 	 * @since 6.2.0
 	 *
+	 * @see https://html.spec.whatwg.org/multipage/parsing.html#rcdata-state
+	 *
 	 * @param string $tag_name – the lowercase tag name which will close the RCDATA region.
 	 * @return bool Whether an end to the RCDATA region was found before the end of the document.
 	 */
@@ -1281,11 +1285,11 @@ class WP_HTML_Tag_Processor {
 	 * Converts class name updates into tag attributes updates
 	 * (they are accumulated in different data formats for performance).
 	 *
-	 * @see $lexical_updates
-	 * @see $classname_updates
-	 *
 	 * @since 6.2.0
 	 *
+	 * @see WP_HTML_Tag_Processor::$lexical_updates
+	 * @see WP_HTML_Tag_Processor::$classname_updates
+	 *
 	 * @return void
 	 */
 	private function class_name_updates_to_attributes_updates() {
@@ -1740,8 +1744,6 @@ class WP_HTML_Tag_Processor {
 	 * > case-insensitive match for each other.
 	 *     - HTML 5 spec
 	 *
-	 * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
-	 *
 	 * Example:
 	 * ```php
 	 * $p = new WP_HTML_Tag_Processor( '<div data-ENABLED class="test" DATA-test-id="14">Test</div>' );
@@ -1754,6 +1756,8 @@ class WP_HTML_Tag_Processor {
 	 *
 	 * @since 6.2.0
 	 *
+	 * @see https://html.spec.whatwg.org/multipage/syntax.html#attributes-2:ascii-case-insensitive
+	 *
 	 * @param string $prefix Prefix of requested attribute names.
 	 * @return array|null List of attribute names, or `null` when no tag opener is matched.
 	 */
@@ -1778,7 +1782,7 @@ class WP_HTML_Tag_Processor {
 	 *
 	 * Example:
 	 * ```php
-	 * $p = new WP_HTML_Tag_Processor( '<DIV CLASS="test">Test</DIV>' );
+	 * $p = new WP_HTML_Tag_Processor( '<div class="test">Test</div>' );
 	 * $p->next_tag() === true;
 	 * $p->get_tag() === 'DIV';
 	 *
@@ -2095,7 +2099,8 @@ class WP_HTML_Tag_Processor {
 	 * Returns the string representation of the HTML Tag Processor.
 	 *
 	 * @since 6.2.0
-	 * @see get_updated_html
+	 *
+	 * @see WP_HTML_Tag_Processor::get_updated_html()
 	 *
 	 * @return string The processed HTML.
 	 */