Docs: Improve documentation for block pattern properties.

Includes:
* Adding the `templateTypes` property to the `WP_Block_Patterns_Registry::register()` DocBlock.
* Adding `@since` notes for the `postTypes` and `templateTypes` properties to:
 * `_register_theme_block_patterns()`
 * `WP_Block_Patterns_Registry::register()`
* Bringing some consistency to the order of properties between:
 * `_register_theme_block_patterns()`
 * `WP_Block_Patterns_Registry::register()`
 * `WP_REST_Block_Patterns_Controller::prepare_item_for_response()`
 * `WP_REST_Block_Patterns_Controller::get_item_schema()`

Follow-up to [52943], [53152], [54263], [55168].

See #56792.

git-svn-id: https://develop.svn.wordpress.org/trunk@55173 602fd350-edb4-49c9-b593-d223f7449a82

3 files changed, 39 insertions, 35 deletions

diff --git a/src/wp-includes/block-patterns.php b/src/wp-includes/block-patterns.php
index 05bb6817eb..ff3d03cd43 100644
--- a/src/wp-includes/block-patterns.php
+++ b/src/wp-includes/block-patterns.php
@@ -298,14 +298,16 @@ function _register_remote_theme_patterns() {
  *
  *   - Description
  *   - Viewport Width
+ *   - Inserter         (yes/no)
  *   - Categories       (comma-separated values)
  *   - Keywords         (comma-separated values)
  *   - Block Types      (comma-separated values)
  *   - Post Types       (comma-separated values)
  *   - Template Types   (comma-separated values)
- *   - Inserter         (yes/no)
  *
  * @since 6.0.0
+ * @since 6.1.0 The `postTypes` property was added.
+ * @since 6.2.0 The `templateTypes` property was added.
  * @access private
  */
 function _register_theme_block_patterns() {
@@ -314,11 +316,11 @@ function _register_theme_block_patterns() {
 		'slug'          => 'Slug',
 		'description'   => 'Description',
 		'viewportWidth' => 'Viewport Width',
+		'inserter'      => 'Inserter',
 		'categories'    => 'Categories',
 		'keywords'      => 'Keywords',
 		'blockTypes'    => 'Block Types',
 		'postTypes'     => 'Post Types',
-		'inserter'      => 'Inserter',
 		'templateTypes' => 'Template Types',
 	);
 
diff --git a/src/wp-includes/class-wp-block-patterns-registry.php b/src/wp-includes/class-wp-block-patterns-registry.php
index a11c99d8c8..8d86b34087 100644
--- a/src/wp-includes/class-wp-block-patterns-registry.php
+++ b/src/wp-includes/class-wp-block-patterns-registry.php
@@ -43,6 +43,8 @@ final class WP_Block_Patterns_Registry {
 	 *
 	 * @since 5.5.0
 	 * @since 5.8.0 Added support for the `blockTypes` property.
+	 * @since 6.1.0 Added support for the `postTypes` property.
+	 * @since 6.2.0 Added support for the `templateTypes` property.
 	 *
 	 * @param string $pattern_name       Block pattern name including namespace.
 	 * @param array  $pattern_properties {
@@ -50,17 +52,18 @@ final class WP_Block_Patterns_Registry {
 	 *
 	 *     @type string $title         Required. A human-readable title for the pattern.
 	 *     @type string $content       Required. Block HTML markup for the pattern.
-	 *     @type string $description   Optional. Visually hidden text used to describe the pattern in the
-	 *                                 inserter. A description is optional, but is strongly
+	 *     @type string $description   Optional. Visually hidden text used to describe the pattern
+	 *                                 in the inserter. A description is optional, but is strongly
 	 *                                 encouraged when the title does not fully describe what the
 	 *                                 pattern does. The description will help users discover the
 	 *                                 pattern while searching.
 	 *     @type int    $viewportWidth Optional. The intended width of the pattern to allow for a scaled
 	 *                                 preview within the pattern inserter.
-	 *     @type array  $categories    Optional. A list of registered pattern categories used to group block
-	 *                                 patterns. Block patterns can be shown on multiple categories.
-	 *                                 A category must be registered separately in order to be used
-	 *                                 here.
+	 *     @type array  $categories    Optional. A list of registered pattern categories used to group
+	 *                                 block patterns. Block patterns can be shown on multiple categories.
+	 *                                 A category must be registered separately in order to be used here.
+	 *     @type array  $keywords      Optional. A list of aliases or keywords that help users discover
+	 *                                 the pattern while searching.
 	 *     @type array  $blockTypes    Optional. A list of block names including namespace that could use
 	 *                                 the block pattern in certain contexts (placeholder, transforms).
 	 *                                 The block pattern is available in the block editor inserter
@@ -68,12 +71,11 @@ final class WP_Block_Patterns_Registry {
 	 *                                 Certain blocks support further specificity besides the block name
 	 *                                 (e.g. for `core/template-part` you can specify areas
 	 *                                 like `core/template-part/header` or `core/template-part/footer`).
-	 *     @type array  $postTypes     An array of post types that the pattern is restricted to be used with.
-	 *                                 The pattern will only be available when editing one of the post types
-	 *                                 passed on the array. For all the other post types not part of the array
-	 *                                 the pattern is not available at all.
-	 *     @type array  $keywords      Optional. A list of aliases or keywords that help users discover the
-	 *                                 pattern while searching.
+	 *     @type array  $postTypes     Optional. An array of post types that the pattern is restricted
+	 *                                 to be used with. The pattern will only be available when editing one
+	 *                                 of the post types passed on the array. For all the other post types
+	 *                                 not part of the array the pattern is not available at all.
+	 *     @type array  $templateTypes Optional. An array of template types where the pattern fits.
 	 * }
 	 * @return bool True if the pattern was registered with success and false otherwise.
 	 */
diff --git a/src/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php b/src/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php
index 4d50bfae04..445f8c82f6 100644
--- a/src/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php
+++ b/src/wp-includes/rest-api/endpoints/class-wp-rest-block-patterns-controller.php
@@ -165,14 +165,14 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
 		$keys   = array(
 			'name'          => 'name',
 			'title'         => 'title',
+			'content'       => 'content',
 			'description'   => 'description',
 			'viewportWidth' => 'viewport_width',
-			'blockTypes'    => 'block_types',
-			'postTypes'     => 'post_types',
+			'inserter'      => 'inserter',
 			'categories'    => 'categories',
 			'keywords'      => 'keywords',
-			'content'       => 'content',
-			'inserter'      => 'inserter',
+			'blockTypes'    => 'block_types',
+			'postTypes'     => 'post_types',
 			'templateTypes' => 'template_types',
 		);
 		$data   = array();
@@ -213,6 +213,12 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),
+				'content'        => array(
+					'description' => __( 'The pattern content.' ),
+					'type'        => 'string',
+					'readonly'    => true,
+					'context'     => array( 'view', 'edit', 'embed' ),
+				),
 				'description'    => array(
 					'description' => __( 'The pattern detailed description.' ),
 					'type'        => 'string',
@@ -225,15 +231,9 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),
-				'block_types'    => array(
-					'description' => __( 'Block types that the pattern is intended to be used with.' ),
-					'type'        => 'array',
-					'readonly'    => true,
-					'context'     => array( 'view', 'edit', 'embed' ),
-				),
-				'post_types'     => array(
-					'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
-					'type'        => 'array',
+				'inserter'       => array(
+					'description' => __( 'Determines whether the pattern is visible in inserter.' ),
+					'type'        => 'boolean',
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),
@@ -249,21 +249,21 @@ class WP_REST_Block_Patterns_Controller extends WP_REST_Controller {
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),
-				'template_types' => array(
-					'description' => __( 'An array of template types where the pattern fits.' ),
+				'block_types'    => array(
+					'description' => __( 'Block types that the pattern is intended to be used with.' ),
 					'type'        => 'array',
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),
-				'content'        => array(
-					'description' => __( 'The pattern content.' ),
-					'type'        => 'string',
+				'post_types'     => array(
+					'description' => __( 'An array of post types that the pattern is restricted to be used with.' ),
+					'type'        => 'array',
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),
-				'inserter'       => array(
-					'description' => __( 'Determines whether the pattern is visible in inserter.' ),
-					'type'        => 'boolean',
+				'template_types' => array(
+					'description' => __( 'An array of template types where the pattern fits.' ),
+					'type'        => 'array',
 					'readonly'    => true,
 					'context'     => array( 'view', 'edit', 'embed' ),
 				),