Block Processor: Rename extract_block() method for clearer documentation.

In testing during the release candidacy for WordPress 6.9 it was found
that the `extract_block()` method may do more work than is expected
based off of its name.

This change renames the method to `extract_full_block_and_advance()` to
communicate that it does move the Block Processor forward and to hint at
the fact that it also encompasses all inner blocks during that advance.

Developed in WordPress/wordpress-develop#10538
Discussed in https://core.trac.wordpress.org/ticket/61401

Follow-up to [60939].

Props dlh, dmsnell, jonsurrell, westonruter.

See #61401.

Built from https://develop.svn.wordpress.org/trunk@61294


git-svn-id: http://core.svn.wordpress.org/trunk@60606 1a063a9b-81f0-0310-95a4-ce76da25c4cd

Author: dmsnell

wp-includes/class-wp-block-processor.php

@@ -194,7 +194,7 @@
  * block, and re-serialize it into the original document. It’s possible to do so
  * while skipping over the parse of the rest of the document.
  *
- * {@see self::extract_block()} will scan forward from the current block opener
+ * {@see self::extract_full_block_and_advance()} will scan forward from the current block opener
  * and build the parsed block structure until the current block is closed. It will
  * include all inner HTML and inner blocks, and parse all of the inner blocks. It
  * can be used to extract a block at any depth in the document, helpful for operating
@@ -207,7 +207,7 @@
  *     }
  *
  *     $gallery_at    = $processor->get_span()->start;
- *     $gallery_block = $processor->extract_block();
+ *     $gallery_block = $processor->extract_full_block_and_advance();
  *     $after_gallery = $processor->get_span()->start;
  *     return (
  *         substr( $post_content, 0, $gallery_at ) .
@@ -1223,7 +1223,7 @@ public function get_depth(): int {
 	 *     }
 	 *
 	 *     $gallery_at  = $processor->get_span()->start;
-	 *     $gallery     = $processor->extract_block();
+	 *     $gallery     = $processor->extract_full_block_and_advance();
 	 *     $ends_before = $processor->get_span();
 	 *     $ends_before = $ends_before->start ?? strlen( $post_content );
 	 *
@@ -1254,7 +1254,7 @@ public function get_depth(): int {
 	 *     }
 	 * }
 	 */
-	public function extract_block(): ?array {
+	public function extract_full_block_and_advance(): ?array {
 		if ( $this->is_html() ) {
 			$chunk = $this->get_html_content();
 
@@ -1291,7 +1291,7 @@ public function extract_block(): ?array {
 			 * @todo Use iteration instead of recursion, or at least refactor to tail-call form.
 			 */
 			if ( $this->opens_block() ) {
-				$inner_block             = $this->extract_block();
+				$inner_block             = $this->extract_full_block_and_advance();
 				$block['innerBlocks'][]  = $inner_block;
 				$block['innerContent'][] = null;
 			}

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '7.0-alpha-61291';
+$wp_version = '7.0-alpha-61294';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.