Docs: describe return type of _get_block_template_file().

[oandregal]

It was brought up at https://core.trac.wordpress.org/ticket/57756#comment:16 that some inline comments introduced at #4097 could be graduated to a PHP DocBlock for better maintenance: use single place for documenting them as well as enable the existing automated docs to pick them up.

This PR removes the inline comments and makes them part of the _get_block_template_file().

---

SVN commit message:

Docs: describe return type of `_get_block_template_file()`.

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

[oandregal]

An alternative I considered was to make them part of the functions _add_block_template_part_area_info() and _add_block_template_info for wp_template_part and wp_template, respectively.

The role of these functions is to augment the metadata of the template (title + area, or title + postTypes) provided as a parameter. These functions only work with a subset of the template properties (slug as input). It doesn't feel right to have them document what the respective template structure is for a lack of a better place.

[oandregal]

@mukeshpanchal27 @desrosj is there any other feedback you want addressed?

[costdev]

Thanks for the PR @oandregal! Just a couple of minor suggestions. The rest looks good to me!

[oandregal]

@mukeshpanchal27 @costdev @desrosj anyone available to give me a green check on this one, so I can commit?

[costdev]

Thanks for the updates @oandregal! LGTM 👍

[desrosj]

Looks good to me, just left a small nit. Sorry for the delay!

[desrosj]

I find myself wanting all of the optional items at the end of the list. This area of the standards looks relevant here, but there's no mention that optional parameters should all be at the end.

If order is not important, let's just move $area ahead of $title to group optional parameters together.

[costdev]

I don't see any uses in Core that depend on the order. This is a private function, but even still, I checked if we know any plugins/themes that use it. The only two mentions of it are in Gutenberg, whose implementation doesn't seem to depend on order, and a small plugin that defines the function itself, so it seems reordering is somewhat "safe".

I'm not sure whether it's better to put optional elements at the end, or to accurately document the return value should we ever (for some reason) use array_values() on it. An alternative could be to reorder the actual return value as well as the documentation, though that seems more involved that we might want to do here.

[oandregal]

Commited at https://core.trac.wordpress.org/changeset/55744