[wp-trac] [WordPress Trac] #50110: Incorrect property docblocks in WP_Block_Type

[WordPress Trac]

#50110: Incorrect property docblocks in WP_Block_Type
------------------------------------+-----------------------------
 Reporter:  nielsdeblaauw           |      Owner:  (none)
     Type:  defect (bug)            |     Status:  new
 Priority:  normal                  |  Milestone:  Awaiting Review
Component:  Editor                  |    Version:  5.0
 Severity:  minor                   |   Keywords:
  Focuses:  docs, coding-standards  |
------------------------------------+-----------------------------
 In the class WP_Block_Type the docblocks declare `@var #TYPE#` for several
 properties of the class.

 Below I will use `attributes` as an example, but this counts for all the
 following properties:
 - render_callback
 - attributes
 - editor_script
 - script
 - editor_style
 - style


 The docblock defines that the property must be a certain value ('array' in
 the case of attributes), but it is not set in the constructor and is
 optionally set in the `set_props()` method, if `args` has been supplied
 with the correct property.

 {{{#!php
 /**
  * Block type attributes property schemas.
  *
  * @since 5.0.0
  * @var array
  */
 public $attributes;
 }}}

 This allows the property to be null, which conflicts with de docblock.

 == Proposed solution(s)

 === 1. Declare default value:
 This might change behavior, where null is expected (see `get_attributes()`
 for example)

 {{{#!php
 /**
  * Block type attributes property schemas.
  *
  * @since 5.0.0
  * @var array
  */
 public $attributes = array();
 }}}

 === 2. Add possible null to docblock
 This would lead might lead to other conflicts, such as using the the null
 value as an array without a type check.

 {{{#!php
 /**
  * Block type attributes property schemas.
  *
  * @since 5.0.0
  * @var array|null
  */
 public $attributes;
 }}}

 === 3. Do not declare @var
 The `set_props()` method currently does not do any type checking, so in
 theory all the properties listed above are `mixed`.

 ''(intentionally borked example)''
 {{{#!php
 new \WP_Block_Type( 'name', array(
     'attributes' => 'This is not an array.'
 ) );
 }}}

 This places responsibility of type checking on implementing code, which
 would be most 'correct' with the current `set_props()` method.

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