WordPress.org
Get WordPress

Make WordPress Core

Changeset 25644


Ignore:
Timestamp:
09/28/2013 09:28:03 PM (11 years ago)
Author:
DrewAPicture
Message:

Improve inline documentation for the Walker class.

Includes previously undocumented parameters.

See #23406.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/class-wp-walker.php

    r24377 r25644  
    33 * A class for displaying various tree-like structures.
    44 *
    5  * Extend the Walker class to use it, see examples at the below. Child classes
     5 * Extend the Walker class to use it, see examples below. Child classes
    66 * do not need to implement all of the abstract methods in the class. The child
    7  * only needs to implement the methods that are needed. Also, the methods are
    8  * not strictly abstract in that the parameter definition needs to be followed.
    9  * The child classes can have additional parameters.
     7 * only needs to implement the methods that are needed.
    108 *
     9 * @since 2.1.0
     10 *
    1111 * @package WordPress
    12  * @since 2.1.0
    1312 * @abstract
    1413 */
    … …  
    4443     * Starts the list before the elements are added.
    4544     *
    46      * Additional parameters are used in child classes. The args parameter holds
    47      * additional values that may be used with the child class methods. This
    48      * method is called at the start of the output list.
     45     * The $args parameter holds additional values that may be used with the child
     46     * class methods. This method is called at the start of the output list.
    4947     *
    5048     * @since 2.1.0
    … …  
    5250     *
    5351     * @param string $output Passed by reference. Used to append additional content.
     52     * @param int    $depth  Depth of the item.
     53     * @param array  $args   An array of additional arguments.
    5454     */
    5555    function start_lvl( &$output, $depth = 0, $args = array() ) {}
    … …  
    5858     * Ends the list of after the elements are added.
    5959     *
    60      * Additional parameters are used in child classes. The args parameter holds
    61      * additional values that may be used with the child class methods. This
    62      * method finishes the list at the end of output of the elements.
     60     * The $args parameter holds additional values that may be used with the child
     61     * class methods. This method finishes the list at the end of output of the elements.
    6362     *
    6463     * @since 2.1.0
    … …  
    6665     *
    6766     * @param string $output Passed by reference. Used to append additional content.
    68      */
    69     function end_lvl( &$output, $depth = 0, $args = array() )   {}
     67     * @param int    $depth  Depth of the item.
     68     * @param array  $args   An array of additional arguments.
     69     */
     70    function end_lvl( &$output, $depth = 0, $args = array() ) {}
    7071
    7172    /**
    7273     * Start the element output.
    7374     *
    74      * Additional parameters are used in child classes. The args parameter holds
    75      * additional values that may be used with the child class methods. Includes
    76      * the element output also.
     75     * The $args parameter holds additional values that may be used with the child
     76     * class methods. Includes the element output also.
    7777     *
    7878     * @since 2.1.0
    7979     * @abstract
    8080     *
     81     * @param string $output            Passed by reference. Used to append additional content.
     82     * @param object $object            The data object.
     83     * @param int    $depth             Depth of the item.
     84     * @param array  $args              An array of additional arguments.
     85     * @param int    $current_object_id ID of the current item.
     86     */
     87    function start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 ) {}
     88
     89    /**
     90     * Ends the element output, if needed.
     91     *
     92     * The $args parameter holds additional values that may be used with the child class methods.
     93     *
     94     * @since 2.1.0
     95     * @abstract
     96     *
    8197     * @param string $output Passed by reference. Used to append additional content.
    82      */
    83     function start_el( &$output, $object, $depth = 0, $args = array(), $current_object_id = 0 )  {}
    84 
    85     /**
    86      * Ends the element output, if needed.
    87      *
    88      * Additional parameters are used in child classes. The args parameter holds
    89      * additional values that may be used with the child class methods.
    90      *
    91      * @since 2.1.0
    92      * @abstract
    93      *
    94      * @param string $output Passed by reference. Used to append additional content.
    95      */
    96     function end_el( &$output, $object, $depth = 0, $args = array() )    {}
     98     * @param object $object The data object.
     99     * @param int    $depth  Depth of the item.
     100     * @param array  $args   An array of additional arguments.
     101     */
     102    function end_el( &$output, $object, $depth = 0, $args = array() ) {}
    97103
    98104    /**
    … …  
    104110     * max depth to include all depths, see walk() method.
    105111     *
    106      * This method shouldn't be called directly, use the walk() method instead.
     112     * This method should not be called directly, use the walk() method instead.
    107113     *
    108114     * @since 2.5.0
    109115     *
    110      * @param object $element Data object
    111      * @param array $children_elements List of elements to continue traversing.
    112      * @param int $max_depth Max depth to traverse.
    113      * @param int $depth Depth of current element.
    114      * @param array $args
    115      * @param string $output Passed by reference. Used to append additional content.
     116     * @param object $element           Data object.
     117     * @param array  $children_elements List of elements to continue traversing.
     118     * @param int    $max_depth        Max depth to traverse.
     119     * @param int    $depth            Depth of current element.
     120     * @param array  $args              An array of arguments.
     121     * @param string $output            Passed by reference. Used to append additional content.
    116122     * @return null Null on failure with no changes to parameters.
    117123     */
    … …  
    161167     * Display array of elements hierarchically.
    162168     *
    163      * It is a generic function which does not assume any existing order of
    164      * elements. max_depth = -1 means flatly display every element. max_depth =
    165      * 0 means display all levels. max_depth > 0  specifies the number of
    166      * display levels.
    167      *
    168      * @since 2.1.0
    169      *
    170      * @param array $elements
    171      * @param int $max_depth
    172      * @return string
     169     * Does not assume any existing order of elements.
     170     *
     171     * $max_depth = -1 means flatly display every element.
     172     * $max_depth = 0 means display all levels.
     173     * $max_depth > 0 specifies the number of display levels.
     174     *
     175     * @since 2.1.0
     176     *
     177     * @param array $elements  An array of elements.
     178     * @param int   $max_depth The maximum hierarchical depth.
     179     * @return string The hierarchical item output.
    173180     */
    174181    function walk( $elements, $max_depth) {
    … …  
    195202
    196203        /*
    197          * need to display in hierarchical order
    198          * separate elements into two buckets: top level and children elements
    199          * children_elements is two dimensional array, eg.
    200          * children_elements[10][] contains all sub-elements whose parent is 10.
     204         * Need to display in hierarchical order.
     205         * Separate elements into two buckets: top level and children elements.
     206         * Children_elements is two dimensional array, eg.
     207         * Children_elements[10][] contains all sub-elements whose parent is 10.
    201208         */
    202209        $top_level_elements = array();
    … …  
    210217
    211218        /*
    212          * when none of the elements is top level
    213          * assume the first one must be root of the sub elements
     219         * When none of the elements is top level.
     220         * Assume the first one must be root of the sub elements.
    214221         */
    215222        if ( empty($top_level_elements) ) {
    … …  
    232239
    233240        /*
    234          * if we are displaying all levels, and remaining children_elements is not empty,
    235          * then we got orphans, which should be displayed regardless
     241         * If we are displaying all levels, and remaining children_elements is not empty,
     242         * then we got orphans, which should be displayed regardless.
    236243         */
    237244        if ( ( $max_depth == 0 ) && count( $children_elements ) > 0 ) {
    … …  
    252259     * belonging to that page, then lists them and all of their children in hierarchical order.
    253260     *
    254      * @package WordPress
    255      * @since 2.7
    256      * @param int $max_depth = 0 means display all levels; $max_depth > 0 specifies the number of display levels.
    257      * @param int $page_num the specific page number, beginning with 1.
    258      * @return XHTML of the specified page of elements
     261     * $max_depth = 0 means display all levels.
     262     * $max_depth > 0 specifies the number of display levels.
     263     *
     264     * @since 2.7.0
     265     *
     266     * @param int $max_depth The maximum hierarchical depth.
     267     * @param int $page_num  The specific page number, beginning with 1.
     268     * @return string XHTML of the specified page of elements
    259269     */
    260270    function paged_walk( $elements, $max_depth, $page_num, $per_page ) {
    … …  
    310320
    311321        /*
    312          * separate elements into two buckets: top level and children elements
    313          * children_elements is two dimensional array, eg.
    314          * children_elements[10][] contains all sub-elements whose parent is 10.
     322         * Separate elements into two buckets: top level and children elements.
     323         * Children_elements is two dimensional array, e.g.
     324         * $children_elements[10][] contains all sub-elements whose parent is 10.
    315325         */
    316326        $top_level_elements = array();
    … …  
    343353            $count++;
    344354
    345             //for the last page, need to unset earlier children in order to keep track of orphans
     355            // For the last page, need to unset earlier children in order to keep track of orphans.
    346356            if ( $end >= $total_top && $count < $start )
    347357                    $this->unset_children( $e, $children_elements );
    … …  
    378388    }
    379389
    380     // unset all the children for a given top level element
     390    // Unset all the children for a given top level element.
    381391    function unset_children( $e, &$children_elements ){
    382392
    … …  
    395405
    396406    }
    397 }
     407
     408} // Walker
Note: See TracChangeset for help on using the changeset viewer.