PHPDoc

src/wp-includes/blocks.php

@@ -764,15 +764,32 @@ function get_hooked_blocks( $name ) {
 }
 
 /**
- * Returns a function that...
+ * Returns a function that injects the theme attribute into, and hooked blocks before, a given block.
+ *
+ * The returned function can be used as `$pre_callback` argument to `traverse_and_serialize_block(s)`,
+ * where it will inject the `theme` attribute into all Template Part blocks, and prepend the markup for
+ * any blocks hooked `before` the given block and as its parent's `first_child`, respectively.
  *
  * @since 6.4.0
  * @access private
  *
  * @param WP_Block_Template|array $context A block template, template part, or pattern that the blocks belong to.
- * @return callable A function that returns the serialized markup for the given block.
+ * @return callable A function that returns the serialized markup for the given block,
+ *                  including the markup for any hooked blocks before it.
  */
 function make_before_block_visitor( $context ) {
+	/**
+	 * Injects hooked blocks before the given block, injects the `theme` attribute into Template Part blocks, and returns the serialized markup.
+	 *
+	 * If the current block is a Template Part block, inject the `theme` attribute.
+	 * Furthermore, prepend the markup for any blocks hooked `before` the given block and as its parent's
+	 * `first_child`, respectively, to the serialized markup for the given block.
+	 *
+	 * @param array $block  The block to inject the theme attribute into, and hooked blocks before.
+	 * @param array $parent The parent block of the given block.
+	 * @param array $prev   The previous sibling block of the given block.
+	 * @return string The serialized markup for the given block, with the markup for any hooked blocks prepended to it.
+	 */
 	return function( &$block, $parent = null, $prev = null ) use ( $context ) {
 		_inject_theme_attribute_in_template_part_block( $block );
 
@@ -814,7 +831,32 @@ function make_before_block_visitor( $context ) {
 	};
 }
 
+/**
+ * Returns a function that injects the hooked blocks after a given block.
+ *
+ * The returned function can be used as `$post_callback` argument to `traverse_and_serialize_block(s)`,
+ * where it will append the markup for any blocks hooked `after` the given block and as its parent's
+ * `last_child`, respectively.
+ *
+ * @since 6.4.0
+ * @access private
+ *
+ * @param WP_Block_Template|array $context A block template, template part, or pattern that the blocks belong to.
+ * @return callable A function that returns the serialized markup for the given block,
+ *                  including the markup for any hooked blocks after it.
+ */
 function make_after_block_visitor( $context ) {
+	/**
+	 * Injects hooked blocks after the given block, and returns the serialized markup.
+	 *
+	 * Append the markup for any blocks hooked `after` the given block and as its parent's
+	 * `last_child`, respectively, to the serialized markup for the given block.
+	 *
+	 * @param array $block  The block to inject the hooked blocks after.
+	 * @param array $parent The parent block of the given block.
+	 * @param array $next   The next sibling block of the given block.
+	 * @return string The serialized markup for the given block, with the markup for any hooked blocks appended to it.
+	 */
 	return function( &$block, $parent = null, $next = null ) use ( $context ) {
 		$markup = '';