Make WordPress Core

Changeset 58084


Ignore:
Timestamp:
05/02/2024 07:52:42 PM (10 months ago)
Author:
johnbillion
Message:

Docs: Document the array shapes for parsed blocks, template part areas, and template types.

See #60699

Location:
trunk/src/wp-includes
Files:
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/block-template-utils.php

    r58071 r58084  
    5454 * @since 5.9.0
    5555 *
    56  * @return array[] The supported template part area values.
     56 * @return array[] {
     57 *     The allowed template part area values.
     58 *
     59 *     @type array ...$0 {
     60 *         Data for the allowed template part area.
     61 *
     62 *         @type string $area        Template part area name.
     63 *         @type string $label       Template part area label.
     64 *         @type string $description Template part area description.
     65 *         @type string $icon        Template part area icon.
     66 *         @type string $area_tag    Template part area tag.
     67 *     }
     68 * }
    5769 */
    5870function get_allowed_block_template_part_areas() {
     
    92104     * @since 5.9.0
    93105     *
    94      * @param array[] $default_area_definitions An array of supported area objects.
     106     * @param array[] $default_area_definitions {
     107     *     The allowed template part area values.
     108     *
     109     *     @type array ...$0 {
     110     *         Data for the template part area.
     111     *
     112     *         @type string $area        Template part area name.
     113     *         @type string $label       Template part area label.
     114     *         @type string $description Template part area description.
     115     *         @type string $icon        Template part area icon.
     116     *         @type string $area_tag    Template part area tag.
     117     *     }
     118     * }
    95119     */
    96120    return apply_filters( 'default_wp_template_part_areas', $default_area_definitions );
     
    104128 * @since 5.9.0
    105129 *
    106  * @return array[] The default template types.
     130 * @return array[] {
     131 *     The default template types.
     132 *
     133 *     @type array ...$0 {
     134 *         Data for the template type.
     135 *
     136 *         @type string $title       Template type title.
     137 *         @type string $description Template type description.
     138 *    }
     139 * }
    107140 */
    108141function get_default_block_template_types() {
     
    179212     * @since 5.9.0
    180213     *
    181      * @param array[] $default_template_types An array of template types, formatted as [ slug => [ title, description ] ].
     214     * @param array[] $default_template_types {
     215     *     The default template types.
     216     *
     217     *     @type array ...$0 {
     218     *         Data for the template type.
     219     *
     220     *         @type string $title       Template type title.
     221     *         @type string $description Template type description.
     222     *    }
     223     * }
    182224     */
    183225    return apply_filters( 'default_template_types', $default_template_types );
  • trunk/src/wp-includes/blocks.php

    r57677 r58084  
    12021202 * @since 5.3.1
    12031203 *
    1204  * @param array $block A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1204 * @param array $block {
     1205 *     A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1206 *
     1207 *     @type string   $blockName    Name of block.
     1208 *     @type array    $attrs        Attributes from block comment delimiters.
     1209 *     @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1210 *                                  have the same structure as this one.
     1211 *     @type string   $innerHTML    HTML from inside block comment delimiters.
     1212 *     @type array    $innerContent List of string fragments and null markers where
     1213 *                                  inner blocks were found.
     1214 * }
    12051215 * @return string String of rendered HTML.
    12061216 */
     
    12301240 * @since 5.3.1
    12311241 *
    1232  * @param array[] $blocks An array of representative arrays of parsed block objects. See serialize_block().
     1242 * @param array[] $blocks {
     1243 *     Array of block structures.
     1244 *
     1245 *     @type array ...$0 {
     1246 *         A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1247 *
     1248 *         @type string   $blockName    Name of block.
     1249 *         @type array    $attrs        Attributes from block comment delimiters.
     1250 *         @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1251 *                                      have the same structure as this one.
     1252 *         @type string   $innerHTML    HTML from inside block comment delimiters.
     1253 *         @type array    $innerContent List of string fragments and null markers where
     1254 *                                      inner blocks were found.
     1255 *     }
     1256 * }
    12331257 * @return string String of rendered HTML.
    12341258 */
     
    16391663 * @global WP_Post $post The post to edit.
    16401664 *
    1641  * @param array $parsed_block A single parsed block object.
     1665 * @param array $parsed_block {
     1666 *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     1667 *
     1668 *     @type string   $blockName    Name of block.
     1669 *     @type array    $attrs        Attributes from block comment delimiters.
     1670 *     @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1671 *                                  have the same structure as this one.
     1672 *     @type string   $innerHTML    HTML from inside block comment delimiters.
     1673 *     @type array    $innerContent List of string fragments and null markers where
     1674 *                                  inner blocks were found.
     1675 * }
    16421676 * @return string String of rendered HTML.
    16431677 */
     
    16531687     *
    16541688     * @param string|null   $pre_render   The pre-rendered content. Default null.
    1655      * @param array         $parsed_block The block being rendered.
     1689     * @param array         $parsed_block {
     1690     *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     1691     *
     1692     *     @type string   $blockName    Name of block.
     1693     *     @type array    $attrs        Attributes from block comment delimiters.
     1694     *     @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1695     *                                  have the same structure as this one.
     1696     *     @type string   $innerHTML    HTML from inside block comment delimiters.
     1697     *     @type array    $innerContent List of string fragments and null markers where
     1698     *                                  inner blocks were found.
     1699     * }
    16561700     * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
    16571701     */
     
    16691713     * @since 5.9.0 The `$parent_block` parameter was added.
    16701714     *
    1671      * @param array         $parsed_block The block being rendered.
    1672      * @param array         $source_block An un-modified copy of $parsed_block, as it appeared in the source content.
     1715     * @param array         $parsed_block {
     1716     *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     1717     *
     1718     *     @type string   $blockName    Name of block.
     1719     *     @type array    $attrs        Attributes from block comment delimiters.
     1720     *     @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1721     *                                  have the same structure as this one.
     1722     *     @type string   $innerHTML    HTML from inside block comment delimiters.
     1723     *     @type array    $innerContent List of string fragments and null markers where
     1724     *                                  inner blocks were found.
     1725     * }
     1726     * @param array         $source_block {
     1727     *     An un-modified copy of `$parsed_block`, as it appeared in the source content.
     1728     *     See WP_Block_Parser_Block.
     1729     *
     1730     *     @type string   $blockName    Name of block.
     1731     *     @type array    $attrs        Attributes from block comment delimiters.
     1732     *     @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1733     *                                  have the same structure as this one.
     1734     *     @type string   $innerHTML    HTML from inside block comment delimiters.
     1735     *     @type array    $innerContent List of string fragments and null markers where
     1736     *                                  inner blocks were found.
     1737     * }
    16731738     * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
    16741739     */
     
    16961761     *
    16971762     * @param array         $context      Default context.
    1698      * @param array         $parsed_block Block being rendered, filtered by `render_block_data`.
     1763     * @param array         $parsed_block {
     1764     *     A representative array of the block being rendered. See WP_Block_Parser_Block.
     1765     *
     1766     *     @type string   $blockName    Name of block.
     1767     *     @type array    $attrs        Attributes from block comment delimiters.
     1768     *     @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1769     *                                  have the same structure as this one.
     1770     *     @type string   $innerHTML    HTML from inside block comment delimiters.
     1771     *     @type array    $innerContent List of string fragments and null markers where
     1772     *                                  inner blocks were found.
     1773     * }
    16991774     * @param WP_Block|null $parent_block If this is a nested block, a reference to the parent block.
    17001775     */
     
    17121787 *
    17131788 * @param string $content Post content.
    1714  * @return array[] Array of parsed block objects.
     1789 * @return array[] {
     1790 *     Array of block structures.
     1791 *
     1792 *     @type array ...$0 {
     1793 *         A representative array of a single parsed block object. See WP_Block_Parser_Block.
     1794 *
     1795 *         @type string   $blockName    Name of block.
     1796 *         @type array    $attrs        Attributes from block comment delimiters.
     1797 *         @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     1798 *                                      have the same structure as this one.
     1799 *         @type string   $innerHTML    HTML from inside block comment delimiters.
     1800 *         @type array    $innerContent List of string fragments and null markers where
     1801 *                                      inner blocks were found.
     1802 *     }
     1803 * }
    17151804 */
    17161805function parse_blocks( $content ) {
  • trunk/src/wp-includes/class-wp-block-parser.php

    r56945 r58084  
    5050
    5151    /**
    52      * Parses a document and returns a list of block structures
     52     * Parses a document and returns a list of block structures.
    5353     *
    5454     * When encountering an invalid parse will return a best-effort
     
    5959     *
    6060     * @param string $document Input document being parsed.
    61      * @return array[]
     61     * @return array[] {
     62     *     Array of block structures.
     63     *
     64     *     @type array ...$0 {
     65     *         A representative array of a single parsed block object. See WP_Block_Parser_Block.
     66     *
     67     *         @type string   $blockName    Name of block.
     68     *         @type array    $attrs        Attributes from block comment delimiters.
     69     *         @type array[]  $innerBlocks  List of inner blocks. An array of arrays that
     70     *                                      have the same structure as this one.
     71     *         @type string   $innerHTML    HTML from inside block comment delimiters.
     72     *         @type array    $innerContent List of string fragments and null markers where
     73     *                                      inner blocks were found.
     74     *     }
     75     * }
    6276     */
    6377    public function parse( $document ) {
  • trunk/src/wp-includes/class-wp-block.php

    r57700 r58084  
    114114     * @since 5.5.0
    115115     *
    116      * @param array                  $block             Array of parsed block properties.
     116     * @param array                  $block             {
     117     *     A representative array of a single parsed block object. See WP_Block_Parser_Block.
     118     *
     119     *     @type string   $blockName    Name of block.
     120     *     @type array    $attrs        Attributes from block comment delimiters.
     121     *     @type array    $innerBlocks  List of inner blocks. An array of arrays that
     122     *                                  have the same structure as this one.
     123     *     @type string   $innerHTML    HTML from inside block comment delimiters.
     124     *     @type array    $innerContent List of string fragments and null markers where inner blocks were found.
     125     * }
    117126     * @param array                  $available_context Optional array of ancestry context values.
    118127     * @param WP_Block_Type_Registry $registry          Optional block type registry.
Note: See TracChangeset for help on using the changeset viewer.