From 55ee499f4eb02f80765096bff85251a010555d12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=83=C2=A9?= <oandregal@git.wordpress.org>
Date: Thu, 11 May 2023 09:01:55 +0000
Subject: [PATCH] Docs: describe return type of `_get_block_template_file()`.

Props: desrosj, mukesh27, costdev, johnbillion.
Fixes #57756.


git-svn-id: https://develop.svn.wordpress.org/trunk@55744 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/block-template-utils.php | 33 +++++++++---------------
 1 file changed, 12 insertions(+), 21 deletions(-)

diff --git a/src/wp-includes/block-template-utils.php b/src/wp-includes/block-template-utils.php
index d6c2589c86..a34caff00d 100644
--- a/src/wp-includes/block-template-utils.php
+++ b/src/wp-includes/block-template-utils.php
@@ -249,7 +249,18 @@ function _get_block_templates_paths( $base_directory ) {
  *
  * @param string $template_type 'wp_template' or 'wp_template_part'.
  * @param string $slug          Template slug.
- * @return array|null Template.
+ * @return array|null {
+ *    Array with template metadata if $template_type is one of 'wp_template' or 'wp_template_part'.
+ *    null otherwise.
+ *
+ *    @type string   $slug      Template slug.
+ *    @type string   $path      Template file path.
+ *    @type string   $theme     Theme slug.
+ *    @type string   $type      Template type.
+ *    @type string   $area      Template area. Only for 'wp_template_part'.
+ *    @type string   $title     Optional. Template title.
+ *    @type string[] $postTypes Optional. List of post types that the template supports. Only for 'wp_template'.
+ * }
  */
 function _get_block_template_file( $template_type, $slug ) {
 	if ( 'wp_template' !== $template_type && 'wp_template_part' !== $template_type ) {
@@ -357,16 +368,6 @@ function _get_block_templates_files( $template_type, $query = array() ) {
 			);
 
 			if ( 'wp_template_part' === $template_type ) {
-				/*
-				 * Structure of a wp_template_part item:
-				 *
-				 * - slug
-				 * - path
-				 * - theme
-				 * - type
-				 * - area
-				 * - title (optional)
-				 */
 				$candidate = _add_block_template_part_area_info( $new_template_item );
 				if ( ! isset( $area ) || ( isset( $area ) && $area === $candidate['area'] ) ) {
 					$template_files[] = $candidate;
@@ -374,16 +375,6 @@ function _get_block_templates_files( $template_type, $query = array() ) {
 			}
 
 			if ( 'wp_template' === $template_type ) {
-				/*
-				 * Structure of a wp_template item:
-				 *
-				 * - slug
-				 * - path
-				 * - theme
-				 * - type
-				 * - title (optional)
-				 * - postTypes (optional)
-				 */
 				$candidate = _add_block_template_info( $new_template_item );
 				if (
 					! $post_type ||