[wp-trac] [WordPress Trac] #63753: Incorrect PHPDocs in class WP_Block_List

[WordPress Trac]

#63753: Incorrect PHPDocs in class WP_Block_List
--------------------------+-----------------------------
 Reporter:  marian1       |      Owner:  (none)
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:
 Severity:  minor         |   Keywords:
  Focuses:  docs          |
--------------------------+-----------------------------
 `WP_Block_List` represents a list of block instances. It implements both
 `ArrayAccess` and `Iterator`. The container property `$blocks` is
 initially populated via the constructor, which expects a `$blocks`
 argument — an array containing either parsed block data or block
 instances.

 As the block parser returns an array with integer keys, it is reasonable
 to assume that the `$blocks` argument is also expected to be an array with
 integer keys. This assumption is supported by the unit tests for
 `WP_Block_List`.

 However, the `$offset` argument in the following methods is documented as
 a `string` rather than an `int`:

 - `offsetExists()`
 - `offsetGet()`
 - `offsetSet()`
 - `offsetUnset()`

 Additionally, the type of the offset value is documented as `mixed` rather
 than `WP_Block|null` and `array|WP_Block` in:

 - `offsetGet()`
 - `offsetSet()`

 Likewise, the return types of the following methods are overly broad and
 can be narrowed:

 - `current()` is documented as `mixed` but should be `WP_Block|null`
 - `key()` is documented as `mixed` but should be `int|null`

 These changes would align the documentation with the intended usage of
 `WP_Block_List`. However, it should be noted that neither the constructor
 nor the `offsetGet()` method actually validate or enforce the types of the
 arguments.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/63753>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform