WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.phpdoc.diff

File taxonomy.phpdoc.diff, 7.4 KB (added by darkdragon, 11 years ago)
  • taxonomy.php

     
    44// Taxonomy Registration
    55//
    66
     7/**
     8 * @global array $wp_taxonomies Fill me out please
     9 */
    710$wp_taxonomies = array();
    811$wp_taxonomies['category'] = (object) array('name' => 'category', 'object_type' => 'post', 'hierarchical' => true, 'update_count_callback' => '_update_post_term_count');
    912$wp_taxonomies['post_tag'] = (object) array('name' => 'post_tag', 'object_type' => 'post', 'hierarchical' => false, 'update_count_callback' => '_update_post_term_count');
    1013$wp_taxonomies['link_category'] = (object) array('name' => 'link_category', 'object_type' => 'link', 'hierarchical' => false);
    1114
     15/**
     16 * get_object_taxonomies() - Appears to return all of the names that are of $object_type
     17 *
     18 * It appears that this function can be used to find all of the names inside of
     19 * $wp_taxonomies global variable.
     20 *
     21 * @example
     22 *      <?php $taxonomies = get_object_taxonomies('post'); ?>
     23 *      Should result in <pre>Array(
     24 *      'category',
     25 *      'post_tag'
     26 *      )</pre>
     27 *
     28 * @package Taxonomy
     29 * @global array $wp_taxonomies
     30 * @param string $object_type Name of the type of taxonomy object
     31 * @return array The names of all within the object_type.
     32 *
     33 * @internal
     34 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     35 *      might be inaccurate or wrong.
     36 */
    1237function get_object_taxonomies($object_type) {
    1338        global $wp_taxonomies;
    1439
     
    2146        return $taxonomies;
    2247}
    2348
     49/**
     50 * get_taxonomy() - Returns the "taxonomy" object of $taxonomy.
     51 *
     52 * The get_taxonomy function will first check that the parameter string given
     53 * is a taxonomy object and if it is, it will return it.
     54 *
     55 * @package Taxonomy
     56 * @global array $wp_taxonomies
     57 * @param string $taxonomy Name of taxonomy object to return
     58 * @return object The Taxonomy Object
     59 *
     60 * @internal
     61 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     62 *      might be inaccurate or wrong.
     63 */
    2464function get_taxonomy( $taxonomy ) {
    2565        global $wp_taxonomies;
    2666
     
    3070        return $wp_taxonomies[$taxonomy];
    3171}
    3272
     73/**
     74 * is_taxonomy() - Checks that the taxonomy name exists
     75 *
     76 * @package Taxonomy
     77 * @global array $wp_taxonomies
     78 * @param string $taxonomy Name of taxonomy object
     79 * @return bool Whether the taxonomy exists or not.
     80 *
     81 * @internal
     82 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     83 *      might be inaccurate or wrong.
     84 */
    3385function is_taxonomy( $taxonomy ) {
    3486        global $wp_taxonomies;
    3587
    3688        return isset($wp_taxonomies[$taxonomy]);       
    3789}
    3890
     91/**
     92 * is_taxonomy_hierarchical() - Whether the taxonomy object is hierarchical
     93 *
     94 * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally
     95 * returns the hierarchical value in the object.
     96 *
     97 * @package Taxonomy
     98 * @global array $wp_taxonomies
     99 * @param string $taxonomy Name of taxonomy object
     100 * @return bool Whether the taxonomy is hierarchical
     101 *
     102 * @internal
     103 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     104 *      might be inaccurate or wrong.
     105 */
    39106function is_taxonomy_hierarchical($taxonomy) {
    40107        if ( ! is_taxonomy($taxonomy) )
    41108                return false;
     
    44111        return $taxonomy->hierarchical;
    45112}
    46113
     114/**
     115 * register_taxonomy() - Create or modify a taxonomy object.
     116 *
     117 * A simple function for creating or modifying a taxonomy object based on the parameters given.
     118 * The function will accept an array (third optional parameter), along with strings for the
     119 * taxonomy name and another string for the object type.
     120 *
     121 * The function keeps a default set, allowing for the $args to be optional but allow the other
     122 * functions to still work. It is possible to overwrite the default set, which contains two
     123 * keys: hierarchical and update_count_callback.
     124 *
     125 * hierarachical has some defined purpose at other parts of the API, but is bool value.
     126 *
     127 * update_count_callback works much like a hook, in that it will be called (or something from
     128 *      somewhere).
     129 *
     130 * @package Taxonomy
     131 * @global array $wp_taxonomies
     132 * @param string $taxonomy Name of taxonomy object
     133 * @param string $object_type Name of the object type for the taxonomy object.
     134 * @param array $args See above description for the two keys values.
     135 * @return null Nothing is returned, so expect error maybe or use is_taxonomy() to check.
     136 *
     137 * @internal
     138 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     139 *      might be inaccurate or wrong.
     140 */
    47141function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
    48142        global $wp_taxonomies;
    49143
     
    59153// Term API
    60154//
    61155
     156/**
     157 * get_objects_in_term() - Return object_ids of valid taxonomy and term
     158 *
     159 * The strings of $taxonomies must exist before this function will continue. On failure of finding
     160 * a valid taxonomy, it will return an WP_Error class, kind of like Exceptions in PHP 5, except you
     161 * can't catch them. Even so, you can still test for the WP_Error class and get the error message.
     162 *
     163 * The $terms aren't checked the same as $taxonomies, but still need to exist for $object_ids to
     164 * be returned.
     165 *
     166 * It is possible to change the order that object_ids is returned by either using PHP sort family
     167 * functions or using the database by using $args with either ASC or DESC array. The value should
     168 * be in the key named 'order'.
     169 *
     170 * @package Taxonomy
     171 * @subpackage Term
     172 * @global object $wpdb Database Query
     173 * @param string|array $terms String of term or array of string values of terms that will be used
     174 * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names
     175 * @param array $args Change the order of the object_ids, either ASC or DESC
     176 * @return object WP_Error - A PHP 4 compatible Exception class prototype
     177 * @return array Empty array if there are no $object_ids
     178 * @return array Array of $object_ids
     179 *
     180 * @internal
     181 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     182 *      might be inaccurate or wrong.
     183 */
    62184function get_objects_in_term( $terms, $taxonomies, $args = array() ) {
    63185        global $wpdb;
    64186
     
    90212        return $object_ids;
    91213}
    92214
     215/**
     216 * get_term() -
     217 *
     218 *
     219 *
     220 * @package Taxonomy
     221 * @subpackage Term
     222 * @global object $wpdb Database Query
     223 * @param int|object $term
     224 * @param string $taxonomy
     225 * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N
     226 * @return mixed Term Row from database
     227 *
     228 * @internal
     229 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     230 *      might be inaccurate or wrong.
     231 */
    93232function &get_term(&$term, $taxonomy, $output = OBJECT) {
    94233        global $wpdb;
    95234
     
    124263        }
    125264}
    126265
     266/**
     267 * get_term_by() -
     268 *
     269 *
     270 *
     271 * @package Taxonomy
     272 * @subpackage Term
     273 * @global object $wpdb Database Query
     274 * @param string $field
     275 * @param string $value
     276 * @param string $taxonomy
     277 * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N
     278 * @return mixed Term Row from database
     279 *
     280 * @internal
     281 *      This won't appear but just a note to say that this is all conjecture and parts or whole
     282 *      might be inaccurate or wrong.
     283 */
    127284function get_term_by($field, $value, $taxonomy, $output = OBJECT) {
    128285        global $wpdb;
    129286