Changeset 64436 for trunk/src/wp-includes/class-wp-theme-json.php

Timestamp:

10/17/2026 04:58:15 AM (34 hours ago)

Author:

westonruter

Message:

Docs: Use @link instead of @see for URL references.

The WordPress inline documentation standards for PHP and JavaScript reserve @see for references to functions, methods, classes, and hooks, and use @link for URLs. While phpDocumentor and JSDoc both accept a URL in @see, core had used both forms for external references such as specifications, Trac tickets, and GitHub pull requests, so the remaining @see tags pointing to URLs are converted to @link across core, the bundled themes, core scripts, and the unit tests.

On the touched lines, @see is kept ahead of @link where both appear, per the standards; links to developer.wordpress.org pages for core functions in Twenty Twenty become @see references to those functions; and links that no longer resolve are updated. The block files synced from Gutenberg, the bundled pomo library, and other third-party code are left unchanged, and the HTML API is handled separately.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10804.
Follow-up to r63569.

Props huzaifaalmesbah, westonruter, noruzzaman, shailu25.
See #65860.

File:

• trunk/src/wp-includes/class-wp-theme-json.php (modified) (4 diffs)

trunk/src/wp-includes/class-wp-theme-json.php

@@ -1584 +1584 @@
                  * comma token. The exception are syntax errors, which are not handled here.
                  *
-                 * @see https://www.w3.org/TR/css-syntax-3/#parse-comma-separated-list-of-component-values
+                 * @link https://www.w3.org/TR/css-syntax-3/#parse-comma-separated-list-of-component-values
                  */
                 if ( strlen( $selector ) === strcspn( $selector, '/\'"(<\\' ) ) {
@@ -1633 +1633 @@
                  * comma token. The exception are syntax errors, which are not handled here.
                  *
-                 * @see https://www.w3.org/TR/css-syntax-3/#parse-comma-separated-list-of-component-values
+                 * @link https://www.w3.org/TR/css-syntax-3/#parse-comma-separated-list-of-component-values
                  */
                 if ( strlen( $selector ) === strcspn( $selector, '/\'"(<\\' ) ) {
@@ -1678 +1678 @@
          *     array( '.a /* a, the first *\/', '.b' ) === self::split_selector_list( '.a /* a, the first *\/,.b' );
          *
-         * @see https://www.w3.org/TR/selectors/#parse-selector
-         * @see https://www.w3.org/TR/css-syntax-3/
+         * @link https://www.w3.org/TR/selectors/#parse-selector
+         * @link https://www.w3.org/TR/css-syntax-3/
          *
          * @since 7.1.0
@@ -1786 +1786 @@
                                  * > to U+000A LINE FEED during preprocessing.
                                  *
-                                 * @see https://www.w3.org/TR/css-syntax/#whitespace
-                                 * @see https://www.w3.org/TR/css-syntax/#newline
+                                 * @link https://www.w3.org/TR/css-syntax/#whitespace
+                                 * @link https://www.w3.org/TR/css-syntax/#newline
                                  */
                                 $selectors[] = trim( substr( $selector, $was_at, $next_at - $was_at ), " \t\n" );