Type annotations and feedback nits.

Author: dmsnell

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

@@ -461,7 +461,7 @@ class WP_Block_Processor {
 	 * @see self::INCOMPLETE_INPUT
 	 * @see self::COMPLETE
 	 *
-	 * @since 6.9.0}
+	 * @since 6.9.0
 	 *
 	 * @var string
 	 */
@@ -520,7 +520,7 @@ class WP_Block_Processor {
 	 * For every open block, in hierarchical order, this stores the byte length
 	 * of the block’s block type in the source text. For HTML spans this is 0.
 	 *
-	 * @seince 6.9.0
+	 * @since 6.9.0
 	 *
 	 * @see self::$open_blocks_at
 	 *
@@ -628,7 +628,7 @@ public function __construct( string $source_text ) {
 	 *                                Default is to stop at any block regardless of its type.
 	 * @return bool Whether an opening delimiter for a block was found.
 	 */
-	public function next_block( $block_type = null ) {
+	public function next_block( ?string $block_type = null ): bool {
 		while ( $this->next_delimiter( $block_type ) ) {
 			if ( self::CLOSER !== $this->get_delimiter_type() ) {
 				return true;
@@ -679,7 +679,7 @@ public function next_block( $block_type = null ) {
 	 *                                Defaults to visit every block regardless of type.
 	 * @return bool Whether a block delimiter was matched.
 	 */
-	public function next_delimiter( ?string $block_name = null ) {
+	public function next_delimiter( ?string $block_name = null ): bool {
 		if ( ! isset( $block_name ) ) {
 			while ( $this->next_token() ) {
 				if ( ! $this->is_html() ) {
@@ -733,7 +733,7 @@ public function next_delimiter( ?string $block_name = null ) {
 	 *
 	 * @return bool Whether a token was matched or the end of the document was reached without finding any.
 	 */
-	public function next_token() {
+	public function next_token(): bool {
 		if ( $this->last_error || self::COMPLETE === $this->state || self::INCOMPLETE_INPUT === $this->state ) {
 			return false;
 		}
@@ -1166,9 +1166,9 @@ public function next_token() {
 	 *
 	 * @since 6.9.0
 	 *
-	 * @return array
+	 * @return string[]
 	 */
-	public function get_breadcrumbs() {
+	public function get_breadcrumbs(): array {
 		$breadcrumbs = array_fill( 0, count( $this->open_blocks_at ), null );
 
 		/*
@@ -1196,9 +1196,9 @@ public function get_breadcrumbs() {
 	 *
 	 * @since 6.9.0
 	 *
-	 * @return int|null
+	 * @return int
 	 */
-	public function get_depth() {
+	public function get_depth(): int {
 		return count( $this->open_blocks_at );
 	}
 
@@ -1213,6 +1213,8 @@ public function get_depth() {
 	 * Once this function returns, the parser will be matched on token following the close
 	 * of the given block.
 	 *
+	 * The return type of this method is compatible with the return of {@see \parse_blocks()}.
+	 *
 	 * Example:
 	 *
 	 *     $processor = new WP_Block_Processor( $post_content );
@@ -1236,9 +1238,23 @@ public function get_depth() {
 	 *
 	 * @since 6.9.0
 	 *
-	 * @return array|null Array compatible with {@see \parse_blocks()} for the given block.
+	 * @return array[]|null {
+	 *     Array of block structures.
+	 *
+	 *     @type array ...$0 {
+	 *         An associative array of a single parsed block object. See WP_Block_Parser_Block.
+	 *
+	 *         @type string|null $blockName    Name of block.
+	 *         @type array       $attrs        Attributes from block comment delimiters.
+	 *         @type array[]     $innerBlocks  List of inner blocks. An array of arrays that
+	 *                                         have the same structure as this one.
+	 *         @type string      $innerHTML    HTML from inside block comment delimiters.
+	 *         @type array       $innerContent List of string fragments and null markers where
+	 *                                         inner blocks were found.
+	 *     }
+	 * }
 	 */
-	public function extract_block() {
+	public function extract_block(): ?array {
 		if ( $this->is_html() ) {
 			$chunk = $this->get_html_content_and_advance();
 
@@ -1462,7 +1478,7 @@ public function is_block_type( string $block_type ): bool {
 	 * @param int    $b_length Byte length of second block type.
 	 * @return bool Whether the spans of text represent identical block types, normalized for namespacing.
 	 */
-	public static function are_equal_block_types( $a_text, $a_at, $a_length, $b_text, $b_at, $b_length ): bool {
+	public static function are_equal_block_types( string $a_text, int $a_at, int $a_length, string $b_text, int $b_at, int $b_length ): bool {
 		$a_ns_length = strcspn( $a_text, '/', $a_at, $a_length );
 		$b_ns_length = strcspn( $b_text, '/', $b_at, $b_length );
 
@@ -1676,8 +1692,8 @@ public function get_html_content_and_advance(): ?string {
 	 *
 	 * @see self::are_equal_block_types()
 	 *
-	 * @return string Fully-qualified block namespace and type, e.g. "core/paragraph",
-	 *                if matched on an explicit delimiter, otherwise `null`.
+	 * @return string|null Fully-qualified block namespace and type, e.g. "core/paragraph",
+	 *                     if matched on an explicit delimiter, otherwise `null`.
 	 */
 	public function get_block_type(): ?string {
 		if (
@@ -1730,8 +1746,8 @@ public function get_block_type(): ?string {
 	 *
 	 * @see self::are_equal_block_types()
 	 *
-	 * @return string Fully-qualified block namespace and type, e.g. "core/paragraph",
-	 *                if matched on an explicit delimiter or freeform block, otherwise `null`.
+	 * @return string|null Fully-qualified block namespace and type, e.g. "core/paragraph",
+	 *                     if matched on an explicit delimiter or freeform block, otherwise `null`.
 	 */
 	public function get_printable_block_type(): ?string {
 		if (
@@ -1925,7 +1941,7 @@ public function get_span(): ?WP_HTML_Span {
 	 *
 	 * @see self::$state
 	 *
-	 * @since 6.9.0}
+	 * @since 6.9.0
 	 */
 	const READY = 'processor-ready';
 

tests/phpunit/tests/block-processor/wpBlockProcessor.php

@@ -129,7 +129,7 @@ public function test_finds_open_and_inner_html_and_close_of_post_with_basic_bloc
 		);
 
 		$this->assertSame(
-		'#innerHTML',
+			'#innerHTML',
 			$processor->get_printable_block_type(),
 			'Should have identified the HTML span as inner HTML.'
 		);