Make WordPress Core

Changeset 58084


Ignore:
Timestamp:
05/02/2024 07:52:42 PM (2 years 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.