Docs: Improve documentation for `WP_Block_Type` properties.

Add a reference to `WP_Block_Type::__construct()` for information on accepted arguments in `register_block_type()`.

Synchronize the documentation between several places, use `WP_Block_Type::__construct()` as the canonical source.

Props ediamin, audrasjb, peterwilsoncc.
Fixes #48640.
Built from https://develop.svn.wordpress.org/trunk@50419


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

wp-includes/blocks.php

@@ -15,13 +15,9 @@
  * @param string|WP_Block_Type $name Block type name including namespace, or alternatively
  *                                   a complete WP_Block_Type instance. In case a WP_Block_Type
  *                                   is provided, the $args parameter will be ignored.
- * @param array                $args {
+ * @param array                $args Optional. Array of block type arguments. Accepts any public property
- *     Optional. Array of block type arguments. Accepts any public property of `WP_Block_Type`.
+ *                                   of `WP_Block_Type`. See WP_Block_Type::__construct() for information
- *     Any arguments may be defined, however the ones described below are supported by default.
+ *                                   on accepted arguments. Default empty array.
- *     Default empty array.
- *
- *     @type callable $render_callback Callback used to render blocks of this block type.
- * }
  * @return WP_Block_Type|false The registered block type on success, or false on failure.
  */
 function register_block_type( $name, $args = array() ) {
@@ -190,13 +186,9 @@ function register_block_style_handle( $metadata, $field_name ) {
  *
  * @param string $file_or_folder Path to the JSON file with metadata definition for
  *                               the block or path to the folder where the `block.json` file is located.
- * @param array  $args {
+ * @param array  $args           Optional. Array of block type arguments. Accepts any public property
- *     Optional. Array of block type arguments. Accepts any public property of `WP_Block_Type`.
+ *                               of `WP_Block_Type`. See WP_Block_Type::__construct() for information
- *     Any arguments may be defined, however the ones described below are supported by default.
+ *                               on accepted arguments. Default empty array.
- *     Default empty array.
- *
- *     @type callable $render_callback Callback used to render blocks of this block type.
- * }
  * @return WP_Block_Type|false The registered block type on success, or false on failure.
  */
 function register_block_type_from_metadata( $file_or_folder, $args = array() ) {

wp-includes/class-wp-block-type-registry.php

@@ -34,17 +34,14 @@ final class WP_Block_Type_Registry {
 	 *
 	 * @since 5.0.0
 	 *
+	 * @see WP_Block_Type::__construct()
+	 *
 	 * @param string|WP_Block_Type $name Block type name including namespace, or alternatively
 	 *                                   a complete WP_Block_Type instance. In case a WP_Block_Type
 	 *                                   is provided, the $args parameter will be ignored.
-	 * @param array                $args {
+	 * @param array                $args Optional. Array of block type arguments. Accepts any public property
-	 *     Optional. Array of block type arguments. Accepts any public property of `WP_Block_Type`.
+	 *                                   of `WP_Block_Type`. See WP_Block_Type::__construct() for information
-	 *     Any arguments may be defined, however the ones described below are supported by default.
+	 *                                   on accepted arguments. Default empty array.
-	 *     Default empty array.
-	 *
-	 *     @type callable $render_callback Callback used to render blocks of this block type.
-	 *     @type array    $attributes      Block attributes mapping, property name to schema.
-	 * }
 	 * @return WP_Block_Type|false The registered block type on success, or false on failure.
 	 */
 	public function register( $name, $args = array() ) {

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

@@ -33,60 +33,83 @@ class WP_Block_Type {
 	public $name;
 
 	/**
+	 * Human-readable block type label.
+	 *
 	 * @since 5.5.0
 	 * @var string
 	 */
 	public $title = '';
 
 	/**
+	 * Block type category classification, used in search interfaces
+	 * to arrange block types by category.
+	 *
 	 * @since 5.5.0
 	 * @var string|null
 	 */
 	public $category = null;
 
 	/**
+	 * Setting parent lets a block require that it is only available
+	 * when nested within the specified blocks.
+	 *
 	 * @since 5.5.0
 	 * @var array|null
 	 */
 	public $parent = null;
 
 	/**
+	 * Block type icon.
+	 *
 	 * @since 5.5.0
 	 * @var string|null
 	 */
 	public $icon = null;
 
 	/**
+	 * A detailed block type description.
+	 *
 	 * @since 5.5.0
 	 * @var string
 	 */
 	public $description = '';
 
 	/**
+	 * Additional keywords to produce block type as result
+	 * in search interfaces.
+	 *
 	 * @since 5.5.0
 	 * @var array
 	 */
 	public $keywords = array();
 
 	/**
+	 * The translation textdomain.
+	 *
 	 * @since 5.5.0
 	 * @var string|null
 	 */
 	public $textdomain = null;
 
 	/**
+	 * Alternative block styles.
+	 *
 	 * @since 5.5.0
 	 * @var array
 	 */
 	public $styles = array();
 
 	/**
+	 * Supported features.
+	 *
 	 * @since 5.5.0
 	 * @var array|null
 	 */
 	public $supports = null;
 
 	/**
+	 * Structured data for the block preview.
+	 *
 	 * @since 5.5.0
 	 * @var array|null
 	 */
@@ -166,8 +189,33 @@ class WP_Block_Type {
 	 * @see register_block_type()
 	 *
 	 * @param string       $block_type Block type name including namespace.
-	 * @param array|string $args       Optional. Array or string of arguments for registering a block type.
+	 * @param array|string $args       {
-	 *                                 Default empty array.
+	 *     Optional. Array or string of arguments for registering a block type. Any arguments may be defined,
+	 *     however the ones described below are supported by default. Default empty array.
+	 *
+	 *
+	 *     @type string        $title            Human-readable block type label.
+	 *     @type string|null   $category         Block type category classification, used in
+	 *                                           search interfaces to arrange block types by category.
+	 *     @type array|null    $parent           Setting parent lets a block require that it is only
+	 *                                           available when nested within the specified blocks.
+	 *     @type string|null   $icon             Block type icon.
+	 *     @type string        $description      A detailed block type description.
+	 *     @type array         $keywords         Additional keywords to produce block type as
+	 *                                           result in search interfaces.
+	 *     @type string|null   $textdomain       The translation textdomain.
+	 *     @type array         $styles           Alternative block styles.
+	 *     @type array|null    $supports         Supported features.
+	 *     @type array|null    $example          Structured data for the block preview.
+	 *     @type callable|null $render_callback  Block type render callback.
+	 *     @type array|null    $attributes       Block type attributes property schemas.
+	 *     @type array         $uses_context     Context values inherited by blocks of this type.
+	 *     @type array|null    $provides_context Context provided by blocks of this type.
+	 *     @type string|null   $editor_script    Block type editor script handle.
+	 *     @type string|null   $script           Block type front end script handle.
+	 *     @type string|null   $editor_style     Block type editor style handle.
+	 *     @type string|null   $style            Block type front end style handle.
+	 * }
 	 */
 	public function __construct( $block_type, $args = array() ) {
 		$this->name = $block_type;
@@ -259,6 +307,7 @@ class WP_Block_Type {
 	 * @since 5.0.0
 	 *
 	 * @param array|string $args Array or string of arguments for registering a block type.
+	 *                           See WP_Block_Type::__construct() for information on accepted arguments.
 	 */
 	public function set_props( $args ) {
 		$args = wp_parse_args(

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.7-beta3-50418';
+$wp_version = '5.7-beta3-50419';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.