WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.phpdoc.diff

File taxonomy.phpdoc.diff, 7.4 KB (added by darkdragon, 8 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