More documentation improvements

Author: sirreal

src/wp-includes/html-api/class-wp-css-attribute-selector.php

@@ -217,7 +217,7 @@ public function matches( WP_HTML_Tag_Processor $processor ): bool {
 	 *
 	 * @param string $input
 	 *
-	 * @return Generator<string>
+	 * @return Generator<string> Yields each whitespace-delimited value from the input string.
 	 */
 	private function whitespace_delimited_list( string $input ): Generator {
 		// Start by skipping whitespace.

src/wp-includes/html-api/class-wp-css-complex-selector.php

@@ -99,7 +99,7 @@ final class WP_CSS_Complex_Selector extends WP_CSS_Selector_Parser_Matcher {
 	 * Constructor.
 	 *
 	 * @param WP_CSS_Compound_Selector $self_selector The selector in the final position.
-	 * @param array{WP_CSS_Type_Selector, string}[]|null $selectors The context selectors.
+	 * @param array{WP_CSS_Type_Selector, string}[]|null $context_selectors The context selectors.
 	 */
 	private function __construct(
 		WP_CSS_Compound_Selector $self_selector,
@@ -246,7 +246,7 @@ public static function parse( string $input, int &$offset ) {
 				return null;
 			}
 
-			/** @var array{WP_CSS_Compound_Selector, string} */
+			/** @var array{WP_CSS_Type_Selector, string} */
 			$selector_pair = array( $self_selector->type_selector, $combinator );
 			$selectors[]   = $selector_pair;
 			$self_selector = $next_selector;

src/wp-includes/html-api/class-wp-css-compound-selector-list.php

@@ -51,9 +51,7 @@
  * - ID selectors (e.g. `#unique-id`)
  * - Attribute selectors (e.g. `[attribute-name]` or `[attribute-name="value"]`)
  * - Comma-separated selector lists (e.g. `.selector-1, .selector-2`)
- * - The following combinators. Only type (element) selectors are allowed in non-final position:
- *   - descendant (e.g. `el .descendant`)
- *   - child (`el > .child`)
+ * - Compound selectors (e.g. `div.class-name#id[attr]`)
  *
  * Unsupported selector syntax:
  * - Pseudo-element selectors (`::before`)

src/wp-includes/html-api/class-wp-css-selector-parser-matcher.php

@@ -123,7 +123,7 @@ final protected static function parse_hash_token( string $input, int &$offset ):
 	 * the <bad-string-token> is not a part of the selector grammar. That
 	 * case is treated as failure to parse and null is returned.
 	 *
-	 * @return string|null
+	 * @return string|null The parsed string token value, or null if parsing failed.
 	 */
 	final protected static function parse_string( string $input, int &$offset ): ?string {
 		if ( $offset >= strlen( $input ) ) {
@@ -278,7 +278,7 @@ final protected static function consume_escaped_codepoint( $input, &$offset ): s
 	 *
 	 * https://www.w3.org/TR/css-syntax-3/#consume-name
 	 *
-	 * @return string|null
+	 * @return string|null The parsed identifier name, or null if parsing failed.
 	 */
 	final protected static function parse_ident( string $input, int &$offset ): ?string {
 		if ( ! self::check_if_three_code_points_would_start_an_ident_sequence( $input, $offset ) ) {