Improve select_ method arguments, docs, implementation

Author: sirreal

src/wp-includes/html-api/class-wp-html-processor.php

@@ -636,37 +636,64 @@ public function get_unsupported_exception() {
 	}
 
 	/**
-	 * Use a selector to advance.
+	 * Progress through a document pausing on tags matching the provided CSS selector string.
+	 *
+	 * @example
+	 *
+	 *     $processor = WP_HTML_Processor::create_fragment(
+	 *         '<meta charset="utf-8"><title>Example</title><meta property="og:type" content="website"><meta property="og:description" content="An example.">'
+	 *     );
+	 *     foreach ( $processor->select_all( 'meta[property^="og:" i]' ) as $_ ) {
+	 *         // Loop is entered twice.
+	 *         var_dump(
+	 *             $processor->get_tag(),                   // string(4) "META"
+	 *             $processor->get_attribute( 'property' ), // string(7) "og:type" / string(14) "og:description"
+	 *             $processor->get_attribute( 'content' ),  // string(7) "website" / string(11) "An example."
+	 *         );
+	 *     }
 	 *
-	 * @todo _doing_it_wrong on null selector?
+	 * @since TBD
 	 *
-	 * @param string $selectors
-	 * @return Generator<void>
+	 * @param string $selector_string Selector string.
+	 * @return Generator<void> A generator pausing on each tag matching the selector.
 	 */
-	public function select_all( string $selectors ): ?Generator {
-		$select = WP_CSS_Selector::from_selectors( $selectors );
-		if ( null === $select ) {
+	public function select_all( string $selector_string ): ?Generator {
+		$selector = WP_CSS_Selector::from_selectors( $selector_string );
+		if ( null === $selector ) {
 			return;
 		}
 
 		while ( $this->next_tag() ) {
-			if ( $select->matches( $this ) ) {
+			if ( $selector->matches( $this ) ) {
 				yield;
 			}
 		}
 	}
 
 	/**
-	 * Select the next matching element.
+	 * Move to the next tag matching the provided CSS selector string.
 	 *
-	 * If iterating through matching elements, use `select_all` instead.
+	 * This method will stop at the next match. To progress through all matches, use
+	 * the `select_all` method.
 	 *
-	 * @param string $selectors
-	 * @return bool
+	 * @example
+	 *
+	 *     $processor = WP_HTML_Processor::create_fragment(
+	 *         '<meta charset="utf-8"><title>Example</title><meta property="og:title" content="Example">'
+	 *     );
+	 *     $processor->select( 'meta[charset]' );
+	 *     var_dump(
+	 *         $processor->get_tag(),                  // string(4) "META"
+	 *         $processor->get_attribute( 'charset' ), // string(5) "utf-8"
+	 *     );
+	 *
+	 * @since TBD
+	 *
+	 * @param string $selector_string
+	 * @return bool  True if a matching tag was found, otherwise false.
 	 */
-	public function select( string $selectors ) {
-		$selection = $this->select_all( $selectors );
-		foreach ( $selection as $_ ) {
+	public function select( string $selector_string ) {
+		foreach ( $this->select_all( $selector_string ) as $_ ) {
 			return true;
 		}
 		return false;