Skip to content

HTML API: Use @link instead of @see for URL references #14370

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
westonruter wants to merge 6 commits into from
Closed

HTML API: Use @link instead of @see for URL references #14370

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
bc79d41
HTML API: Replace incorrect `@see` usage with `@link`.
huzaifaalmesbah Oct 17, 2026
bfb26eb
Docs: Place `@see` tags before `@link` tags.
westonruter Oct 17, 2026
86c89a3
HTML API: Use inline `{@link}` tags in bulleted spec references.
westonruter Oct 17, 2026
8506feb
HTML API: Replace remaining `@see` tags for URLs with `@link` in tests.
westonruter Oct 17, 2026
6b47dd5
HTML API: Use inline `{@link}` tags in the `WP_HTML_Doctype_Info` des…
westonruter Oct 17, 2026
8e655d9
Integrate links in docblock prose
sirreal Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/wp-includes/html-api/class-wp-html-active-formatting-elements.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@
* @access private
* @ignore
*
* @see https://html.spec.whatwg.org/#list-of-active-formatting-elements
* @see WP_HTML_Processor
* @link https://html.spec.whatwg.org/#list-of-active-formatting-elements
*/
class WP_HTML_Active_Formatting_Elements {
/**
Expand Down Expand Up @@ -95,7 +95,7 @@ public function current_node() {
* > formatting from "leaking" into applet, object, marquee, template,
* > td, th, and caption elements.
*
* @see https://html.spec.whatwg.org/#concept-parser-marker
* @link https://html.spec.whatwg.org/#concept-parser-marker
*
* @since 6.7.0
*/
Expand All @@ -108,7 +108,7 @@ public function insert_marker(): void {
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#push-onto-the-list-of-active-formatting-elements
* @link https://html.spec.whatwg.org/#push-onto-the-list-of-active-formatting-elements
*
* @param WP_HTML_Token $token Push this node onto the stack.
*/
Expand Down Expand Up @@ -215,7 +215,7 @@ public function walk_up() {
* > The list has been cleared up to the last marker.
* > 4. Go to step 1.
*
* @see https://html.spec.whatwg.org/multipage/parsing.html#clear-the-list-of-active-formatting-elements-up-to-the-last-marker
* @link https://html.spec.whatwg.org/multipage/parsing.html#clear-the-list-of-active-formatting-elements-up-to-the-last-marker
*
* @since 6.7.0
*/
Expand Down
8 changes: 4 additions & 4 deletions src/wp-includes/html-api/class-wp-html-decoder.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,7 +345,7 @@ public static function read_character_reference( $context, $text, $at = 0, &$mat
* This comment is here to note and explain why there's no check to
* remove these characters or replace them.
*
* @see https://infra.spec.whatwg.org/#noncharacter
* @link https://infra.spec.whatwg.org/#noncharacter
*/

/*
Expand Down Expand Up @@ -456,8 +456,8 @@ public static function read_character_reference( $context, $text, $at = 0, &$mat
* `/?random&degree&gt=0&lt=360&not=90` produces the intended
* value regardless of the following character.)
*
* @see https://html.spec.whatwg.org/multipage/parsing.html#named-character-reference-state
* @see https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references
* @link https://html.spec.whatwg.org/multipage/parsing.html#named-character-reference-state
* @link https://html.spec.whatwg.org/multipage/named-characters.html#named-character-references
*/
if ( 'attribute' !== $context || ';' === $text[ $after_name - 1 ] || $after_name >= $length ) {
$match_byte_length = $after_name - $at;
Expand Down Expand Up @@ -494,7 +494,7 @@ public static function read_character_reference( $context, $text, $at = 0, &$mat
*
* @since 6.6.0
*
* @see https://www.rfc-editor.org/rfc/rfc3629 For the UTF-8 standard.
* @link https://www.rfc-editor.org/rfc/rfc3629 For the UTF-8 standard.
*
* @param int $code_point Which code point to convert.
* @return string Converted code point, or `�` if invalid.
Expand Down
44 changes: 21 additions & 23 deletions src/wp-includes/html-api/class-wp-html-doctype-info.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,27 +27,25 @@
* they match only when byte-for-byte identical (no-quirks mode).
*
* All HTML documents should start with the standard HTML5 DOCTYPE: `<!DOCTYPE html>`.
* The {@link https://html.spec.whatwg.org/#the-doctype HTML Standard} explains why:
*
* > DOCTYPEs are required for legacy reasons. When omitted, browsers tend to use a different
* > rendering mode that is incompatible with some specifications. Including the DOCTYPE in a
* > document ensures that the browser makes a best-effort attempt at following the
* > relevant specifications.
*
* @see https://html.spec.whatwg.org/#the-doctype
*
* DOCTYPE declarations comprise four properties: a name, public identifier, system identifier,
* and an indication of which document compatibility mode they would imply if an HTML parser
* hadn't already determined it from other information.
*
* @see https://html.spec.whatwg.org/#the-initial-insertion-mode
* hadn't already determined it from other information. The HTML parser's
* {@link https://html.spec.whatwg.org/#the-initial-insertion-mode initial insertion mode}

@dmsnell dmsnell Oct 21, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are your thoughts on how these interrupt the flow of the sentences with links? I know that on the rendered docs it will be an inline link, but here in the code where people will be working, the impact is different.

@sirreal sirreal Oct 22, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't mind it in this case:

  • LSP/IDE's probably handle this better
  • Docs will be better
  • I don't find the literal lines of code comments significantly worse.

* defines which compatibility mode a DOCTYPE declaration implies.
*
* Historically, the DOCTYPE declaration was used in SGML documents to instruct a parser how
* Historically, the DOCTYPE declaration was used in
* {@link https://www.iso.org/standard/16387.html SGML documents} to instruct a parser how
* to interpret the various tags and entities within a document. Its role in HTML diverged
* from how it was used in SGML and no meaning should be back-read into HTML based on how it
* is used in SGML, XML, or XHTML documents.
*
* @see https://www.iso.org/standard/16387.html
*
* @since 6.7.0
* @since 7.1.0 Spec update: missing and empty SYSTEM identifiers are handled
* the same for determining the document mode.
Expand All @@ -67,7 +65,7 @@ class WP_HTML_Doctype_Info {
* <!DOCTYPE html>
* ╰──┴── name is "html".
*
* @see https://html.spec.whatwg.org/#tokenization
* @link https://html.spec.whatwg.org/#tokenization
*
* @since 6.7.0
*
Expand All @@ -91,7 +89,7 @@ class WP_HTML_Doctype_Info {
* │ │ ╰─── public identifier ─────╯
* ╰──┴── name is "html".
*
* @see https://html.spec.whatwg.org/#tokenization
* @link https://html.spec.whatwg.org/#tokenization
*
* @since 6.7.0
*
Expand Down Expand Up @@ -121,7 +119,7 @@ class WP_HTML_Doctype_Info {
* │ │ ╰─── public identifier ─────╯ ╰──── system identifier ────╯
* ╰──┴── name is "html".
*
* @see https://html.spec.whatwg.org/#tokenization
* @link https://html.spec.whatwg.org/#tokenization
*
* @since 6.7.0
*
Expand Down Expand Up @@ -149,7 +147,7 @@ class WP_HTML_Doctype_Info {
* before the HTML element has been opened and before finding any other
* DOCTYPE declaration tokens.
*
* @see https://html.spec.whatwg.org/#the-initial-insertion-mode
* @link https://html.spec.whatwg.org/#the-initial-insertion-mode
*
* @since 6.7.0
*
Expand All @@ -171,7 +169,7 @@ class WP_HTML_Doctype_Info {
* > and system identifier must be marked as missing (which is a distinct state from the
* > empty string), and the force-quirks flag must be set to off (its other state is on).
*
* @see https://html.spec.whatwg.org/multipage/parsing.html#tokenization
* @link https://html.spec.whatwg.org/multipage/parsing.html#tokenization
*
* @since 6.7.0
*
Expand Down Expand Up @@ -424,7 +422,7 @@ public static function from_doctype_token( string $doctype_html ): ?self {
* This parser combines the rules for parsing DOCTYPE tokens found in the HTML
* specification for the DOCTYPE related tokenizer states.
*
* @see https://html.spec.whatwg.org/#doctype-state
* @link https://html.spec.whatwg.org/#doctype-state
*/

/*
Expand All @@ -449,8 +447,8 @@ public static function from_doctype_token( string $doctype_html ): ?self {
/*
* Perform newline normalization and ensure the $end value is correct after normalization.
*
* @see https://html.spec.whatwg.org/#preprocessing-the-input-stream
* @see https://infra.spec.whatwg.org/#normalize-newlines
* @link https://html.spec.whatwg.org/#preprocessing-the-input-stream
* @link https://infra.spec.whatwg.org/#normalize-newlines
*/
$doctype_html = str_replace( "\r\n", "\n", $doctype_html );
$doctype_html = str_replace( "\r", "\n", $doctype_html );
Expand Down Expand Up @@ -479,7 +477,7 @@ public static function from_doctype_token( string $doctype_html ): ?self {
* Parsing effectively begins in "Before DOCTYPE name state". Ignore whitespace and
* proceed to the next state.
*
* @see https://html.spec.whatwg.org/#before-doctype-name-state
* @link https://html.spec.whatwg.org/#before-doctype-name-state
*/
$at += strspn( $doctype_html, " \t\n\f\r", $at );

Expand All @@ -502,7 +500,7 @@ public static function from_doctype_token( string $doctype_html ): ?self {
* Find a case-insensitive match for "PUBLIC" or "SYSTEM" at this point.
* Otherwise, set force-quirks and enter bogus DOCTYPE state (skip the rest of the doctype).
*
* @see https://html.spec.whatwg.org/#after-doctype-name-state
* @link https://html.spec.whatwg.org/#after-doctype-name-state
*/
if ( $at + 6 >= $end ) {
return new self( $doctype_name, $doctype_public_id, $doctype_system_id, true );
Expand Down Expand Up @@ -549,8 +547,8 @@ public static function from_doctype_token( string $doctype_html ): ?self {
* "DOCTYPE public identifier (single-quoted) state" by finding one of the valid quotes.
* Anything else forces quirks mode and ignores the rest of the contents.
*
* @see https://html.spec.whatwg.org/#doctype-public-identifier-(double-quoted)-state
* @see https://html.spec.whatwg.org/#doctype-public-identifier-(single-quoted)-state
* @link https://html.spec.whatwg.org/#doctype-public-identifier-(double-quoted)-state
* @link https://html.spec.whatwg.org/#doctype-public-identifier-(single-quoted)-state
*/
$closer_quote = $doctype_html[ $at ];

Expand Down Expand Up @@ -579,7 +577,7 @@ public static function from_doctype_token( string $doctype_html ): ?self {
*
* Advance through whitespace between public and system identifiers.
*
* @see https://html.spec.whatwg.org/#between-doctype-public-and-system-identifiers-state
* @link https://html.spec.whatwg.org/#between-doctype-public-and-system-identifiers-state
*/
$at += strspn( $doctype_html, " \t\n\f\r", $at, $end - $at );
if ( $at >= $end ) {
Expand All @@ -592,8 +590,8 @@ public static function from_doctype_token( string $doctype_html ): ?self {
* "DOCTYPE system identifier (single-quoted) state" by finding one of the valid quotes.
* Anything else forces quirks mode and ignores the rest of the contents.
*
* @see https://html.spec.whatwg.org/#doctype-system-identifier-(double-quoted)-state
* @see https://html.spec.whatwg.org/#doctype-system-identifier-(single-quoted)-state
* @link https://html.spec.whatwg.org/#doctype-system-identifier-(double-quoted)-state
* @link https://html.spec.whatwg.org/#doctype-system-identifier-(single-quoted)-state
*/
$closer_quote = $doctype_html[ $at ];

Expand Down
24 changes: 12 additions & 12 deletions src/wp-includes/html-api/class-wp-html-open-elements.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,8 @@
* @access private
* @ignore
*
* @see https://html.spec.whatwg.org/#stack-of-open-elements
* @see WP_HTML_Processor
* @link https://html.spec.whatwg.org/#stack-of-open-elements
*/
class WP_HTML_Open_Elements {
/**
Expand Down Expand Up @@ -235,7 +235,7 @@ public function current_node_is( string $identity ): bool {
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#has-an-element-in-the-specific-scope
* @link https://html.spec.whatwg.org/#has-an-element-in-the-specific-scope
*
* @param string $tag_name Name of tag check.
* @param string[] $termination_list List of elements that terminate the search.
Expand Down Expand Up @@ -296,7 +296,7 @@ public function has_element_in_specific_scope( string $tag_name, $termination_li
* @since 6.4.0
* @since 6.7.0 Full support.
*
* @see https://html.spec.whatwg.org/#has-an-element-in-scope
* @link https://html.spec.whatwg.org/#has-an-element-in-scope
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
Expand Down Expand Up @@ -345,7 +345,7 @@ public function has_element_in_scope( string $tag_name ): bool {
* @since 6.5.0 Implemented: no longer throws on every invocation.
* @since 6.7.0 Supports all required HTML elements.
*
* @see https://html.spec.whatwg.org/#has-an-element-in-list-item-scope
* @link https://html.spec.whatwg.org/#has-an-element-in-list-item-scope
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
Expand Down Expand Up @@ -395,7 +395,7 @@ public function has_element_in_list_item_scope( string $tag_name ): bool {
* @since 6.4.0
* @since 6.7.0 Supports all required HTML elements.
*
* @see https://html.spec.whatwg.org/#has-an-element-in-button-scope
* @link https://html.spec.whatwg.org/#has-an-element-in-button-scope
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
Expand Down Expand Up @@ -444,7 +444,7 @@ public function has_element_in_button_scope( string $tag_name ): bool {
* @since 6.4.0
* @since 6.7.0 Full implementation.
*
* @see https://html.spec.whatwg.org/#has-an-element-in-table-scope
* @link https://html.spec.whatwg.org/#has-an-element-in-table-scope
*
* @param string $tag_name Name of tag to check.
* @return bool Whether given element is in scope.
Expand Down Expand Up @@ -491,7 +491,7 @@ public function has_element_in_select_scope( string $tag_name ): bool {
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#has-an-element-in-button-scope
* @link https://html.spec.whatwg.org/#has-an-element-in-button-scope
*
* @return bool Whether a P is in BUTTON scope.
*/
Expand All @@ -504,7 +504,7 @@ public function has_p_in_button_scope(): bool {
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#stack-of-open-elements
* @link https://html.spec.whatwg.org/#stack-of-open-elements
*
* @return bool Whether a node was popped off of the stack.
*/
Expand Down Expand Up @@ -556,7 +556,7 @@ public function pop_until( string $html_tag_name ): bool {
*
* @since 6.4.0
*
* @see https://html.spec.whatwg.org/#stack-of-open-elements
* @link https://html.spec.whatwg.org/#stack-of-open-elements
*
* @param WP_HTML_Token $stack_item Item to add onto stack.
*/
Expand Down Expand Up @@ -774,7 +774,7 @@ public function after_element_pop( WP_HTML_Token $item ): void {
* > that the UA must, while the current node is not a table, template, or html element, pop
* > elements from the stack of open elements.
*
* @see https://html.spec.whatwg.org/multipage/parsing.html#clear-the-stack-back-to-a-table-context
* @link https://html.spec.whatwg.org/multipage/parsing.html#clear-the-stack-back-to-a-table-context
*
* @since 6.7.0
*/
Expand All @@ -798,7 +798,7 @@ public function clear_to_table_context(): void {
* > means that the UA must, while the current node is not a tbody, tfoot, thead, template, or
* > html element, pop elements from the stack of open elements.
*
* @see https://html.spec.whatwg.org/multipage/parsing.html#clear-the-stack-back-to-a-table-body-context
* @link https://html.spec.whatwg.org/multipage/parsing.html#clear-the-stack-back-to-a-table-body-context
*
* @since 6.7.0
*/
Expand All @@ -824,7 +824,7 @@ public function clear_to_table_body_context(): void {
* > means that the UA must, while the current node is not a tr, template, or html element, pop
* > elements from the stack of open elements.
*
* @see https://html.spec.whatwg.org/multipage/parsing.html#clear-the-stack-back-to-a-table-row-context
* @link https://html.spec.whatwg.org/multipage/parsing.html#clear-the-stack-back-to-a-table-row-context
*
* @since 6.7.0
*/
Expand Down
Loading
Loading