Make WordPress Core

Ticket #5635: 5635.r8889.diff

File 5635.r8889.diff, 24.8 KB (added by jacobsantos, 15 years ago)

Complete inline documentation for classes.php based off of r8889

  • classes.php

     
    11<?php
     2/**
     3 * Holds Most of the WordPress classes.
     4 *
     5 * Some of the other classes are contained in other files. For example, the
     6 * WordPress cache is in cache.php and the WordPress roles API is in
     7 * capabilities.php. The third party libraries are contained in their own
     8 * separate files.
     9 *
     10 * @package WordPress
     11 */
    212
     13/**
     14 * WordPress environment setup class.
     15 *
     16 * @package WordPress
     17 * @since 2.0.0
     18 */
    319class WP {
     20        /**
     21         * Public query variables.
     22         *
     23         * Long list of public query variables.
     24         *
     25         * @since 2.0.0
     26         * @access public
     27         * @var array
     28         */
    429        var $public_query_vars = array('m', 'p', 'posts', 'w', 'cat', 'withcomments', 'withoutcomments', 's', 'search', 'exact', 'sentence', 'debug', 'calendar', 'page', 'paged', 'more', 'tb', 'pb', 'author', 'order', 'orderby', 'year', 'monthnum', 'day', 'hour', 'minute', 'second', 'name', 'category_name', 'tag', 'feed', 'author_name', 'static', 'pagename', 'page_id', 'error', 'comments_popup', 'attachment', 'attachment_id', 'subpost', 'subpost_id', 'preview', 'robots', 'taxonomy', 'term');
    530
     31        /**
     32         * Private query variables.
     33         *
     34         * Long list of private query variables.
     35         *
     36         * @since 2.0.0
     37         * @var array
     38         */
    639        var $private_query_vars = array('offset', 'posts_per_page', 'posts_per_archive_page', 'what_to_show', 'showposts', 'nopaging', 'post_type', 'post_status', 'category__in', 'category__not_in', 'category__and', 'tag__in', 'tag__not_in', 'tag__and', 'tag_slug__in', 'tag_slug__and', 'tag_id', 'post_mime_type', 'perm');
     40
     41        /**
     42         * Extra query variables set by the user.
     43         *
     44         * @since 2.1.0
     45         * @var array
     46         */
    747        var $extra_query_vars = array();
    848
     49        /**
     50         * Query variables for setting up the WordPress Query Loop.
     51         *
     52         * @since 2.0.0
     53         * @var array
     54         */
    955        var $query_vars;
     56
     57        /**
     58         * String parsed to set the query variables.
     59         *
     60         * @since 2.0.0
     61         * @var string
     62         */
    1063        var $query_string;
     64
     65        /**
     66         * Permalink or requested URI.
     67         *
     68         * @since 2.0.0
     69         * @var string
     70         */
    1171        var $request;
     72
     73        /**
     74         * Rewrite rule the request matched.
     75         *
     76         * @since 2.0.0
     77         * @var string
     78         */
    1279        var $matched_rule;
     80
     81        /**
     82         * Rewrite query the request matched.
     83         *
     84         * @since 2.0.0
     85         * @var string
     86         */
    1387        var $matched_query;
     88
     89        /**
     90         * Whether already did the permalink.
     91         *
     92         * @since 2.0.0
     93         * @var bool
     94         */
    1495        var $did_permalink = false;
    1596
     97        /**
     98         * Add name to list of public query variables.
     99         *
     100         * @since 2.1.0
     101         *
     102         * @param string $qv Query variable name.
     103         */
    16104        function add_query_var($qv) {
    17105                if ( !in_array($qv, $this->public_query_vars) )
    18106                        $this->public_query_vars[] = $qv;
    19107        }
    20108
     109        /**
     110         * Set the value of a query variable.
     111         *
     112         * @since 2.3.0
     113         *
     114         * @param string $key Query variable name.
     115         * @param mixed $value Query variable value.
     116         */
    21117        function set_query_var($key, $value) {
    22118                $this->query_vars[$key] = $value;
    23119        }
    24120
     121        /**
     122         * Parse request to find correct WordPress query.
     123         *
     124         * Sets up the query variables based on the request. There are also many
     125         * filters and actions that can be used to further manipulate the result.
     126         *
     127         * @since 2.0.0
     128         *
     129         * @param array|string $extra_query_vars Set the extra query variables.
     130         */
    25131        function parse_request($extra_query_vars = '') {
    26132                global $wp_rewrite;
    27133
     
    111217
    112218                                        // Substitute the substring matches into the query.
    113219                                        eval("@\$query = \"" . addslashes($query) . "\";");
    114                                        
     220
    115221                                        $this->matched_query = $query;
    116222
    117223                                        // Parse the query.
     
    187293                do_action_ref_array('parse_request', array(&$this));
    188294        }
    189295
     296        /**
     297         * Send additional HTTP headers for caching, content type, etc.
     298         *
     299         * Sets the X-Pingback header, 404 status (if 404), Content-type. If showing
     300         * a feed, it will also send last-modified, etag, and 304 status if needed.
     301         *
     302         * @since 2.0.0
     303         */
    190304        function send_headers() {
    191305                @header('X-Pingback: '. get_bloginfo('pingback_url'));
    192306                if ( is_user_logged_in() )
     
    241355                do_action_ref_array('send_headers', array(&$this));
    242356        }
    243357
     358        /**
     359         * Sets the query string property based off of the query variable property.
     360         *
     361         * The 'query_string' filter is deprecated, but still works. Plugins should
     362         * use the 'request' filter instead.
     363         *
     364         * @since 2.0.0
     365         */
    244366        function build_query_string() {
    245367                $this->query_string = '';
    246368                foreach ( (array) array_keys($this->query_vars) as $wpvar) {
     
    259381                }
    260382        }
    261383
     384        /**
     385         * Setup the WordPress Globals.
     386         *
     387         * The query_vars property will be extracted to the GLOBALS. So care should
     388         * be taken when naming global variables that might interfere with the
     389         * WordPress environment.
     390         *
     391         * @global string $query_string Query string for the loop.
     392         * @global int $more Only set, if single page or post.
     393         * @global int $single If single page or post. Only set, if single page or post.
     394         *
     395         * @since 2.0.0
     396         */
    262397        function register_globals() {
    263398                global $wp_query;
    264399                // Extract updated query vars back into global namespace.
     
    277412                }
    278413        }
    279414
     415        /**
     416         * Setup the current user.
     417         *
     418         * @since 2.0.0
     419         */
    280420        function init() {
    281421                wp_get_current_user();
    282422        }
    283423
     424        /**
     425         * Setup the Loop based on the query variables.
     426         *
     427         * @uses WP::$query_vars
     428         * @since 2.0.0
     429         */
    284430        function query_posts() {
    285431                global $wp_the_query;
    286432                $this->build_query_string();
    287433                $wp_the_query->query($this->query_vars);
    288434        }
    289435
     436        /**
     437         * Set the Headers for 404, if permalink is not found.
     438         *
     439         * Issue a 404 if a permalink request doesn't match any posts.  Don't issue
     440         * a 404 if one was already issued, if the request was a search, or if the
     441         * request was a regular query string request rather than a permalink
     442         * request. Issues a 200, if not 404.
     443         *
     444         * @since 2.0.0
     445         */
    290446        function handle_404() {
    291447                global $wp_query;
    292                 // Issue a 404 if a permalink request doesn't match any posts.  Don't
    293                 // issue a 404 if one was already issued, if the request was a search,
    294                 // or if the request was a regular query string request rather than a
    295                 // permalink request.
     448
    296449                if ( (0 == count($wp_query->posts)) && !is_404() && !is_search() && ( $this->did_permalink || (!empty($_SERVER['QUERY_STRING']) && (false === strpos($_SERVER['REQUEST_URI'], '?'))) ) ) {
    297450                        // Don't 404 for these queries if they matched an object.
    298451                        if ( ( is_tag() || is_category() || is_author() ) && $wp_query->get_queried_object() ) {
     
    308461                }
    309462        }
    310463
     464        /**
     465         * Sets up all of the variables required by the WordPress environment.
     466         *
     467         * The action 'wp' has one parameter that references the WP object. It
     468         * allows for accessing the properties and methods to further manipulate the
     469         * object.
     470         *
     471         * @since 2.0.0
     472         *
     473         * @param string|array $query_args Passed to {@link parse_request()}
     474         */
    311475        function main($query_args = '') {
    312476                $this->init();
    313477                $this->parse_request($query_args);
     
    318482                do_action_ref_array('wp', array(&$this));
    319483        }
    320484
     485        /**
     486         * PHP4 Constructor - Does nothing.
     487         *
     488         * Call main() method when ready to run setup.
     489         *
     490         * @since 2.0.0
     491         *
     492         * @return WP
     493         */
    321494        function WP() {
    322495                // Empty.
    323496        }
    324497}
    325498
     499/**
     500 * WordPress Error class.
     501 *
     502 * Container for checking for WordPress errors and error messages. Return
     503 * WP_Error and use {@link is_wp_error()} to check if this class is returned.
     504 * Many core WordPress functions pass this class in the event of an error and
     505 * if not handled properly will result in code errors.
     506 *
     507 * @package WordPress
     508 * @since 2.1.0
     509 */
    326510class WP_Error {
     511        /**
     512         * Stores the list of errors.
     513         *
     514         * @since 2.1.0
     515         * @var array
     516         * @access private
     517         */
    327518        var $errors = array();
     519
     520        /**
     521         * Stores the list of data for error codes.
     522         *
     523         * @since 2.1.0
     524         * @var array
     525         * @access private
     526         */
    328527        var $error_data = array();
    329528
     529        /**
     530         * PHP4 Constructor - Sets up error message.
     531         *
     532         * If code parameter is empty then nothing will be done. It is possible to
     533         * add multiple messages to the same code, but with other methods in the
     534         * class.
     535         *
     536         * All parameters are optional, but if the code parameter is set, then the
     537         * data parameter is optional.
     538         *
     539         * @since 2.1.0
     540         *
     541         * @param string|int $code Error code
     542         * @param string $message Error message
     543         * @param mixed $data Optional. Error data.
     544         * @return WP_Error
     545         */
    330546        function WP_Error($code = '', $message = '', $data = '') {
    331547                if ( empty($code) )
    332548                        return;
     
    337553                        $this->error_data[$code] = $data;
    338554        }
    339555
     556        /**
     557         * Retrieve all error codes.
     558         *
     559         * @since 2.1.0
     560         * @access public
     561         *
     562         * @return array List of error codes, if avaiable.
     563         */
    340564        function get_error_codes() {
    341565                if ( empty($this->errors) )
    342566                        return array();
     
    344568                return array_keys($this->errors);
    345569        }
    346570
     571        /**
     572         * Retrieve first error code available.
     573         *
     574         * @since 2.1.0
     575         * @access public
     576         *
     577         * @return string|int Empty string, if no error codes.
     578         */
    347579        function get_error_code() {
    348580                $codes = $this->get_error_codes();
    349581
     
    353585                return $codes[0];
    354586        }
    355587
     588        /**
     589         * Retrieve all error messages or error messages matching code.
     590         *
     591         * @since 2.1.0
     592         *
     593         * @param string|int $code Optional. Retrieve messages matching code, if exists.
     594         * @return array Error strings on success, or empty array on failure (if using codee parameter).
     595         */
    356596        function get_error_messages($code = '') {
    357597                // Return all messages if no code specified.
    358598                if ( empty($code) ) {
     
    369609                        return array();
    370610        }
    371611
     612        /**
     613         * Get single error message.
     614         *
     615         * This will get the first message available for the code. If no code is
     616         * given then the first code available will be used.
     617         *
     618         * @since 2.1.0
     619         *
     620         * @param string|int $code Optional. Error code to retrieve message.
     621         * @return string
     622         */
    372623        function get_error_message($code = '') {
    373624                if ( empty($code) )
    374625                        $code = $this->get_error_code();
     
    378629                return $messages[0];
    379630        }
    380631
     632        /**
     633         * Retrieve error data for error code.
     634         *
     635         * @since 2.1.0
     636         *
     637         * @param string|int $code Optional. Error code.
     638         * @return mixed Null, if no errors.
     639         */
    381640        function get_error_data($code = '') {
    382641                if ( empty($code) )
    383642                        $code = $this->get_error_code();
     
    387646                return null;
    388647        }
    389648
     649        /**
     650         * Append more error messages to list of error messages.
     651         *
     652         * @since 2.1.0
     653         * @access public
     654         *
     655         * @param string|int $code Error code.
     656         * @param string $message Error message.
     657         * @param mixed $data Optional. Error data.
     658         */
    390659        function add($code, $message, $data = '') {
    391660                $this->errors[$code][] = $message;
    392661                if ( ! empty($data) )
    393662                        $this->error_data[$code] = $data;
    394663        }
    395664
     665        /**
     666         * Add data for error code.
     667         *
     668         * The error code can only contain one error data.
     669         *
     670         * @since 2.1.0
     671         *
     672         * @param mixed $data Error data.
     673         * @param string|int $code Error code.
     674         */
    396675        function add_data($data, $code = '') {
    397676                if ( empty($code) )
    398677                        $code = $this->get_error_code();
     
    401680        }
    402681}
    403682
     683/**
     684 * Check whether variable is a WordPress Error.
     685 *
     686 * Looks at the object and if a WP_Error class. Does not check to see if the
     687 * parent is also WP_Error, so can't inherit WP_Error and still use this
     688 * function.
     689 *
     690 * @since 2.1.0
     691 *
     692 * @param mixed $thing Check if unknown variable is WordPress Error object.
     693 * @return bool True, if WP_Error. False, if not WP_Error.
     694 */
    404695function is_wp_error($thing) {
    405696        if ( is_object($thing) && is_a($thing, 'WP_Error') )
    406697                return true;
    407698        return false;
    408699}
    409700
    410 /*
     701/**
    411702 * A class for displaying various tree-like structures.
    412  * Extend the Walker class to use it, see examples at the bottom
     703 *
     704 * Extend the Walker class to use it, see examples at the below. Child classes
     705 * do not need to implement all of the abstract methods in the class. The child
     706 * only needs to implement the methods that are needed. Also, the methods are
     707 * not strictly abstract in that the parameter definition needs to be followed.
     708 * The child classes can have additional parameters.
     709 *
     710 * @package WordPress
     711 * @since 2.1.0
     712 * @abstract
    413713 */
    414714class Walker {
     715        /**
     716         * What the class handles.
     717         *
     718         * @since 2.1.0
     719         * @var string
     720         * @access public
     721         */
    415722        var $tree_type;
     723
     724        /**
     725         * DB fields to use.
     726         *
     727         * @since 2.1.0
     728         * @var array
     729         * @access protected
     730         */
    416731        var $db_fields;
    417732
    418         //abstract callbacks
     733        /**
     734         * Starts the list before the elements are added.
     735         *
     736         * Additional parameters are used in child classes. The args parameter holds
     737         * additional values that may be used with the child class methods. This
     738         * method is called at the start of the output list.
     739         *
     740         * @since 2.1.0
     741         * @abstract
     742         *
     743         * @param string $output Passed by reference. Used to append additional content.
     744         */
    419745        function start_lvl(&$output) {}
     746
     747        /**
     748         * Ends the list of after the elements are added.
     749         *
     750         * Additional parameters are used in child classes. The args parameter holds
     751         * additional values that may be used with the child class methods. This
     752         * method finishes the list at the end of output of the elements.
     753         *
     754         * @since 2.1.0
     755         * @abstract
     756         *
     757         * @param string $output Passed by reference. Used to append additional content.
     758         */
    420759        function end_lvl(&$output)   {}
     760
     761        /**
     762         * Start the element output.
     763         *
     764         * Additional parameters are used in child classes. The args parameter holds
     765         * additional values that may be used with the child class methods. Includes
     766         * the element output also.
     767         *
     768         * @since 2.1.0
     769         * @abstract
     770         *
     771         * @param string $output Passed by reference. Used to append additional content.
     772         */
    421773        function start_el(&$output)  {}
     774
     775        /**
     776         * Ends the element output, if needed.
     777         *
     778         * Additional parameters are used in child classes. The args parameter holds
     779         * additional values that may be used with the child class methods.
     780         *
     781         * @since 2.1.0
     782         * @abstract
     783         *
     784         * @param string $output Passed by reference. Used to append additional content.
     785         */
    422786        function end_el(&$output)    {}
    423787
    424         /*
    425          * display one element if the element doesn't have any children
    426          * otherwise, display the element and its children
    427          */
     788        /**
     789         * Traverse elements to create list from elements.
     790         *
     791         * Display one element if the element doesn't have any children otherwise,
     792         * display the element and its children. Will only traverse up to the max
     793         * depth and no ignore elements under that depth. It is possible to set the
     794         * max depth to include all depths, see walk() method.
     795         *
     796         * This method shouldn't be called directly, use the walk() method instead.
     797         *
     798         * @since 2.5.0
     799         *
     800         * @param object $element Data object
     801         * @param array $children_elements List of elements to continue traversing.
     802         * @param int $max_depth Max depth to traverse.
     803         * @param int $depth Depth of current element.
     804         * @param array $args
     805         * @param string $output Passed by reference. Used to append additional content.
     806         * @return null Null on failure with no changes to parameters.
     807         */
    428808        function display_element( $element, &$children_elements, $max_depth, $depth=0, $args, &$output ) {
    429809
    430810                if ( !$element )
     
    465845                call_user_func_array(array(&$this, 'end_el'), $cb_args);
    466846        }
    467847
    468         /*
    469         * displays array of elements hierarchically
    470         * it is a generic function which does not assume any existing order of elements
    471         * max_depth = -1 means flatly display every element
    472         * max_depth = 0  means display all levels
    473         * max_depth > 0  specifies the number of display levels.
    474         */
     848        /**
     849         * Display array of elements hierarchically.
     850         *
     851         * It is a generic function which does not assume any existing order of
     852         * elements. max_depth = -1 means flatly display every element. max_depth =
     853         * 0 means display all levels. max_depth > 0  specifies the number of
     854         * display levels.
     855         *
     856         * @since 2.1.0
     857         *
     858         * @param array $elements
     859         * @param int $max_depth
     860         * @return string
     861         */
    475862        function walk( $elements, $max_depth) {
    476863
    477864                $args = array_slice(func_get_args(), 2);
     
    530917                foreach ( $top_level_elements as $e )
    531918                        $this->display_element( $e, $children_elements, $max_depth, 0, $args, $output );
    532919
    533                 /*
    534                 * if we are displaying all levels, and remaining children_elements is not empty,
    535                 * then we got orphans, which should be displayed regardless
    536                 */
     920                /* 
     921                 * if we are displaying all levels, and remaining children_elements is not empty,
     922                 * then we got orphans, which should be displayed regardless
     923                 */
    537924                if ( ( $max_depth == 0 ) && count( $children_elements ) > 0 ) {
    538925                        $empty_array = array();
    539926                        foreach ( $children_elements as $orphans )
     
    545932        }
    546933}
    547934
     935/**
     936 * Create HTML list of pages.
     937 *
     938 * @package WordPress
     939 * @since 2.1.0
     940 * @uses Walker
     941 */
    548942class Walker_Page extends Walker {
     943        /**
     944         * @see Walker::$tree_type
     945         * @since 2.1.0
     946         * @var string
     947         */
    549948        var $tree_type = 'page';
    550         var $db_fields = array ('parent' => 'post_parent', 'id' => 'ID'); //TODO: decouple this
    551949
     950        /**
     951         * @see Walker::$db_fields
     952         * @since 2.1.0
     953         * @todo Decouple this.
     954         * @var array
     955         */
     956        var $db_fields = array ('parent' => 'post_parent', 'id' => 'ID');
     957
     958        /**
     959         * @see Walker::start_lvl()
     960         * @since 2.1.0
     961         *
     962         * @param string $output Passed by reference. Used to append additional content.
     963         * @param int $depth Depth of page. Used for padding.
     964         */
    552965        function start_lvl(&$output, $depth) {
    553966                $indent = str_repeat("\t", $depth);
    554967                $output .= "\n$indent<ul>\n";
    555968        }
    556969
     970        /**
     971         * @see Walker::end_lvl()
     972         * @since 2.1.0
     973         *
     974         * @param string $output Passed by reference. Used to append additional content.
     975         * @param int $depth Depth of page. Used for padding.
     976         */
    557977        function end_lvl(&$output, $depth) {
    558978                $indent = str_repeat("\t", $depth);
    559979                $output .= "$indent</ul>\n";
    560980        }
    561981
     982        /**
     983         * @see Walker::start_el()
     984         * @since 2.1.0
     985         *
     986         * @param string $output Passed by reference. Used to append additional content.
     987         * @param object $page Page data object.
     988         * @param int $depth Depth of page. Used for padding.
     989         * @param int $current_page Page ID.
     990         * @param array $args
     991         */
    562992        function start_el(&$output, $page, $depth, $current_page, $args) {
    563993                if ( $depth )
    564994                        $indent = str_repeat("\t", $depth);
     
    5891019                }
    5901020        }
    5911021
     1022        /**
     1023         * @see Walker::end_el()
     1024         * @since 2.1.0
     1025         *
     1026         * @param string $output Passed by reference. Used to append additional content.
     1027         * @param object $page Page data object. Not used.
     1028         * @param int $depth Depth of page. Not Used.
     1029         */
    5921030        function end_el(&$output, $page, $depth) {
    5931031                $output .= "</li>\n";
    5941032        }
    5951033
    5961034}
    5971035
     1036/**
     1037 * Create HTML dropdown list of pages.
     1038 *
     1039 * @package WordPress
     1040 * @since 2.1.0
     1041 * @uses Walker
     1042 */
    5981043class Walker_PageDropdown extends Walker {
     1044        /**
     1045         * @see Walker::$tree_type
     1046         * @since 2.1.0
     1047         * @var string
     1048         */
    5991049        var $tree_type = 'page';
    600         var $db_fields = array ('parent' => 'post_parent', 'id' => 'ID'); //TODO: decouple this
    6011050
     1051        /**
     1052         * @see Walker::$db_fields
     1053         * @since 2.1.0
     1054         * @todo Decouple this
     1055         * @var array
     1056         */
     1057        var $db_fields = array ('parent' => 'post_parent', 'id' => 'ID');
     1058
     1059        /**
     1060         * @see Walker::start_el()
     1061         * @since 2.1.0
     1062         *
     1063         * @param string $output Passed by reference. Used to append additional content.
     1064         * @param object $page Page data object.
     1065         * @param int $depth Depth of page in reference to parent pages. Used for padding.
     1066         * @param array $args Uses 'selected' argument for selected page to set selected HTML attribute for option element.
     1067         */
    6021068        function start_el(&$output, $page, $depth, $args) {
    6031069                $pad = str_repeat('&nbsp;', $depth * 3);
    6041070
     
    6121078        }
    6131079}
    6141080
     1081/**
     1082 * Create HTML list of categories.
     1083 *
     1084 * @package WordPress
     1085 * @since 2.1.0
     1086 * @uses Walker
     1087 */
    6151088class Walker_Category extends Walker {
     1089        /**
     1090         * @see Walker::$tree_type
     1091         * @since 2.1.0
     1092         * @var string
     1093         */
    6161094        var $tree_type = 'category';
    617         var $db_fields = array ('parent' => 'parent', 'id' => 'term_id'); //TODO: decouple this
    6181095
     1096        /**
     1097         * @see Walker::$db_fields
     1098         * @since 2.1.0
     1099         * @todo Decouple this
     1100         * @var array
     1101         */
     1102        var $db_fields = array ('parent' => 'parent', 'id' => 'term_id');
     1103
     1104        /**
     1105         * @see Walker::start_lvl()
     1106         * @since 2.1.0
     1107         *
     1108         * @param string $output Passed by reference. Used to append additional content.
     1109         * @param int $depth Depth of category. Used for tab indentation.
     1110         * @param array $args Will only append content if style argument value is 'list'.
     1111         */
    6191112        function start_lvl(&$output, $depth, $args) {
    6201113                if ( 'list' != $args['style'] )
    6211114                        return;
     
    6241117                $output .= "$indent<ul class='children'>\n";
    6251118        }
    6261119
     1120        /**
     1121         * @see Walker::end_lvl()
     1122         * @since 2.1.0
     1123         *
     1124         * @param string $output Passed by reference. Used to append additional content.
     1125         * @param int $depth Depth of category. Used for tab indentation.
     1126         * @param array $args Will only append content if style argument value is 'list'.
     1127         */
    6271128        function end_lvl(&$output, $depth, $args) {
    6281129                if ( 'list' != $args['style'] )
    6291130                        return;
     
    6321133                $output .= "$indent</ul>\n";
    6331134        }
    6341135
     1136        /**
     1137         * @see Walker::start_el()
     1138         * @since 2.1.0
     1139         *
     1140         * @param string $output Passed by reference. Used to append additional content.
     1141         * @param object $category Category data object.
     1142         * @param int $depth Depth of category in reference to parents.
     1143         * @param array $args
     1144         */
    6351145        function start_el(&$output, $category, $depth, $args) {
    6361146                extract($args);
    6371147
     
    6971207                }
    6981208        }
    6991209
     1210        /**
     1211         * @see Walker::end_el()
     1212         * @since 2.1.0
     1213         *
     1214         * @param string $output Passed by reference. Used to append additional content.
     1215         * @param object $page Not used.
     1216         * @param int $depth Depth of category. Not used.
     1217         * @param array $args Only uses 'list' for whether should append to output.
     1218         */
    7001219        function end_el(&$output, $page, $depth, $args) {
    7011220                if ( 'list' != $args['style'] )
    7021221                        return;
     
    7061225
    7071226}
    7081227
     1228/**
     1229 * Create HTML dropdown list of Categories.
     1230 *
     1231 * @package WordPress
     1232 * @since 2.1.0
     1233 * @uses Walker
     1234 */
    7091235class Walker_CategoryDropdown extends Walker {
     1236        /**
     1237         * @see Walker::$tree_type
     1238         * @since 2.1.0
     1239         * @var string
     1240         */
    7101241        var $tree_type = 'category';
    711         var $db_fields = array ('parent' => 'parent', 'id' => 'term_id'); //TODO: decouple this
    7121242
     1243        /**
     1244         * @see Walker::$db_fields
     1245         * @since 2.1.0
     1246         * @todo Decouple this
     1247         * @var array
     1248         */
     1249        var $db_fields = array ('parent' => 'parent', 'id' => 'term_id');
     1250
     1251        /**
     1252         * @see Walker::start_el()
     1253         * @since 2.1.0
     1254         *
     1255         * @param string $output Passed by reference. Used to append additional content.
     1256         * @param object $category Category data object.
     1257         * @param int $depth Depth of category. Used for padding.
     1258         * @param array $args Uses 'selected', 'show_count', and 'show_last_update' keys, if they exist.
     1259         */
    7131260        function start_el(&$output, $category, $depth, $args) {
    7141261                $pad = str_repeat('&nbsp;', $depth * 3);
    7151262
     
    7291276        }
    7301277}
    7311278
     1279/**
     1280 * Send XML response back to AJAX request.
     1281 *
     1282 * @package WordPress
     1283 * @since 2.1.0
     1284 */
    7321285class WP_Ajax_Response {
     1286        /**
     1287         * Store XML responses to send.
     1288         *
     1289         * @since 2.1.0
     1290         * @var array
     1291         * @access private
     1292         */
    7331293        var $responses = array();
    7341294
     1295        /**
     1296         * PHP4 Constructor - Passes args to {@link WP_Ajax_Response::add()}.
     1297         *
     1298         * @since 2.1.0
     1299         * @see WP_Ajax_Response::add()
     1300         *
     1301         * @param string|array $args Optional. Will be passed to add() method.
     1302         * @return WP_Ajax_Response
     1303         */
    7351304        function WP_Ajax_Response( $args = '' ) {
    7361305                if ( !empty($args) )
    7371306                        $this->add($args);
    7381307        }
    7391308
    740         // a WP_Error object can be passed in 'id' or 'data'
     1309        /**
     1310         * Append to XML response based on given arguments.
     1311         *
     1312         * The arguments that can be passed in the $args parameter are below. It is
     1313         * also possible to pass a WP_Error object in either the 'id' or 'data'
     1314         * argument. The parameter isn't actually optional, content should be given
     1315         * in order to send the correct response.
     1316         *
     1317         * 'what' argument is a string that is the XMLRPC response type.
     1318         * 'action' argument is a boolean or string that acts like a nonce.
     1319         * 'id' argument can be WP_Error or an integer.
     1320         * 'old_id' argument is false by default or an integer of the previous ID.
     1321         * 'position' argument is an integer or a string with -1 = top, 1 = bottom,
     1322         * html ID = after, -html ID = before.
     1323         * 'data' argument is a string with the content or message.
     1324         * 'supplemental' argument is an array of strings that will be children of
     1325         * the supplemental element.
     1326         *
     1327         * @since 2.1.0
     1328         *
     1329         * @param string|array $args Override defaults.
     1330         * @return string XML response.
     1331         */
    7411332        function add( $args = '' ) {
    7421333                $defaults = array(
    7431334                        'what' => 'object', 'action' => false,
    7441335                        'id' => '0', 'old_id' => false,
    745                         'position' => 1, // -1 = top, 1 = bottom, html ID = after, -html ID = before
     1336                        'position' => 1,
    7461337                        'data' => '', 'supplemental' => array()
    7471338                );
    7481339
     
    8041395                return $x;
    8051396        }
    8061397
     1398        /**
     1399         * Display XML formatted responses.
     1400         *
     1401         * Sets the content type header to text/xml.
     1402         *
     1403         * @since 2.1.0
     1404         */
    8071405        function send() {
    8081406                header('Content-Type: text/xml');
    8091407                echo "<?xml version='1.0' standalone='yes'?><wp_ajax>";