WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.phpdoc.r5900.diff

File taxonomy.phpdoc.r5900.diff, 16.7 KB (added by darkdragon, 10 years ago)

Completed more phpDoc for functions. Fixed some previous descriptions, and added blank descriptions with params and return completed to other functions.

  • taxonomy.php

     
    1313$wp_taxonomies['link_category'] = (object) array('name' => 'link_category', 'object_type' => 'link', 'hierarchical' => false); 
    1414 
    1515/** 
    16  * get_object_taxonomies() - Appears to return all of the names that are of $object_type 
     16 * get_object_taxonomies() - Return all of the taxonomy names that are of $object_type 
    1717 * 
    1818 * It appears that this function can be used to find all of the names inside of 
    1919 * $wp_taxonomies global variable. 
     
    3131 * @return array The names of all within the object_type. 
    3232 * 
    3333 * @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. 
     34 *      This is all conjecture and might be partially or completely inaccurate. 
    3635 */ 
    3736function get_object_taxonomies($object_type) { 
    3837        global $wp_taxonomies; 
     
    5554 * @package Taxonomy 
    5655 * @global array $wp_taxonomies 
    5756 * @param string $taxonomy Name of taxonomy object to return 
    58  * @return object The Taxonomy Object 
     57 * @return object|bool The Taxonomy Object or false if taxonomy doesn't exist 
    5958 * 
    6059 * @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. 
     60 *      This is all conjecture and might be partially or completely inaccurate. 
    6361 */ 
    6462function get_taxonomy( $taxonomy ) { 
    6563        global $wp_taxonomies; 
     
    7977 * @return bool Whether the taxonomy exists or not. 
    8078 * 
    8179 * @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. 
     80 *      This is all conjecture and might be partially or completely inaccurate. 
    8481 */ 
    8582function is_taxonomy( $taxonomy ) { 
    8683        global $wp_taxonomies; 
     
    9491 * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally 
    9592 * returns the hierarchical value in the object. 
    9693 * 
     94 * A false return value, might also mean that the taxonomy does not exist. 
     95 * 
    9796 * @package Taxonomy 
    9897 * @global array $wp_taxonomies 
    9998 * @param string $taxonomy Name of taxonomy object 
    10099 * @return bool Whether the taxonomy is hierarchical 
    101100 * 
    102101 * @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. 
     102 *      This is all conjecture and might be partially or completely inaccurate. 
    105103 */ 
    106104function is_taxonomy_hierarchical($taxonomy) { 
    107105        if ( ! is_taxonomy($taxonomy) ) 
     
    122120 * functions to still work. It is possible to overwrite the default set, which contains two 
    123121 * keys: hierarchical and update_count_callback. 
    124122 * 
    125  * hierarachical has some defined purpose at other parts of the API, but is bool value. 
     123 * hierarachical has some defined purpose at other parts of the API and is a boolean value. 
    126124 * 
    127125 * update_count_callback works much like a hook, in that it will be called (or something from 
    128126 *      somewhere). 
     
    131129 * @global array $wp_taxonomies 
    132130 * @param string $taxonomy Name of taxonomy object 
    133131 * @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. 
     132 * @param array|string $args See above description for the two keys values. 
    135133 * @return null Nothing is returned, so expect error maybe or use is_taxonomy() to check. 
    136134 * 
    137135 * @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. 
     136 *      This is all conjecture and might be partially or completely inaccurate. 
    140137 */ 
    141138function register_taxonomy( $taxonomy, $object_type, $args = array() ) { 
    142139        global $wp_taxonomies; 
     
    172169 * @global object $wpdb Database Query 
    173170 * @param string|array $terms String of term or array of string values of terms that will be used 
    174171 * @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 
     172 * @param array|string $args Change the order of the object_ids, either ASC or DESC 
    176173 * @return object WP_Error - A PHP 4 compatible Exception class prototype 
    177174 * @return array Empty array if there are no $object_ids 
    178175 * @return array Array of $object_ids 
    179176 * 
    180177 * @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. 
     178 *      This is all conjecture and might be partially or completely inaccurate. 
    183179 */ 
    184180function get_objects_in_term( $terms, $taxonomies, $args = array() ) { 
    185181        global $wpdb; 
     
    213209} 
    214210 
    215211/** 
    216  * get_term() -  
     212 * get_term() - Get all Term data from database by Term ID. 
    217213 * 
    218  *  
     214 * The usage of the get_term function is to apply filters to a term object. 
     215 * It is possible to get a term object from the database before applying the 
     216 * filters.  
    219217 * 
     218 * $term ID must be part of $taxonomy, to get from the database. Failure, might be 
     219 * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the 
     220 * get_row method. 
     221 * 
     222 * There are two hooks, one is specifically for each term, named 'get_term', and the second is  
     223 * for the taxonomy name. Both hooks gets the term object, and the taxonomy name as parameters. 
     224 * Both hooks are expected to return a Term object. 
     225 * 
    220226 * @package Taxonomy 
    221227 * @subpackage Term 
    222228 * @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 
     229 * @param int|object $term If integer, will get from database. If object will apply filters and return $term. 
     230 * @param string $taxonomy Taxonomy name that $term is part of. 
     231 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
    226232 * @return mixed Term Row from database 
    227233 * 
    228234 * @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. 
     235 *   This is all conjecture and might be partially or completely inaccurate. 
     236 * 
     237 *   The @filter and @action phpDoc tags is not supported by phpDoc software. It is for custom phpDoc plugin or custom 
     238 *   solution for getting the tag. I would choose to write a custom phpDoc plugin than custom solution. 
    231239 */ 
    232240function &get_term(&$term, $taxonomy, $output = OBJECT) { 
    233241        global $wpdb; 
     
    248256                        wp_cache_add($term, $_term, $taxonomy); 
    249257                } 
    250258        } 
    251  
     259         
     260        /** 
     261         * @internal 
     262         * Filter tag is basically: filter 'type' 'hook_name' 'description' 
     263         * 
     264         * Takes two parameters the term Object and the taxonomy name. Must return term object. 
     265         * @filter object get_term Used in @see get_term() as a catch-all filter for every $term 
     266         */ 
    252267        $_term = apply_filters('get_term', $_term, $taxonomy); 
     268        /** 
     269         * @internal 
     270         * Filter tag is basically: filter 'type' 'hook_name' 'description' 
     271         * 
     272         * Takes two parameters the term Object and the taxonomy name. Must return term object. 
     273         * $taxonomy will be the taxonomy name, so for example, if 'category', it would be 'get_category' 
     274         * as the filter name. 
     275         * Useful for custom taxonomies or plugging into default taxonomies. 
     276         * @filter object get_$taxonomy Used in @see get_term() as specific filter for each $taxonomy. 
     277         */ 
    253278        $_term = apply_filters("get_$taxonomy", $_term, $taxonomy); 
    254279 
    255280        if ( $output == OBJECT ) { 
     
    264289} 
    265290 
    266291/** 
    267  * get_term_by() -  
     292 * get_term_by() - Get all Term data from database by Term field and data. 
    268293 * 
     294 * Warning: $value is not escaped for 'name' $field. You must do it yourself, if required. 
     295 * 
     296 * The default $field is 'id', therefore it is possible to also use null for field, but not 
     297 * recommended that you do so. 
     298 * 
     299 * If $value does not exist, the return value will be false. If $taxonomy exists and $field 
     300 * and $value combinations exist, the Term will be returned. 
    269301 *  
    270  * 
    271302 * @package Taxonomy 
    272303 * @subpackage Term 
    273304 * @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 
     305 * @param string $field Either 'slug', 'name', or 'id' 
     306 * @param string $value Search for this term value 
     307 * @param string $taxonomy Taxonomy Name 
     308 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
    278309 * @return mixed Term Row from database 
    279310 * 
    280311 * @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. 
     312 *      This is all conjecture and might be partially or completely inaccurate. 
    283313 */ 
    284314function get_term_by($field, $value, $taxonomy, $output = OBJECT) { 
    285315        global $wpdb; 
     
    317347        } 
    318348} 
    319349 
     350/** 
     351 * get_term_children() - Merge all term children into a single array. 
     352 * 
     353 * This recursive function will merge all of the children of $term into 
     354 * the same array. 
     355 * 
     356 * Only useful for taxonomies which are hierarchical. 
     357 *  
     358 * @package Taxonomy 
     359 * @subpackage Term 
     360 * @global object $wpdb Database Query 
     361 * @param string $term Name of Term to get children 
     362 * @param string $taxonomy Taxonomy Name 
     363 * @return array List of Term Objects 
     364 * 
     365 * @internal 
     366 *      This is all conjecture and might be partially or completely inaccurate. 
     367 */ 
    320368function get_term_children( $term, $taxonomy ) { 
    321369        if ( ! is_taxonomy($taxonomy) ) 
    322370                return new WP_Error('invalid_taxonomy', __('Invalid Taxonomy')); 
     
    336384        return $children; 
    337385} 
    338386 
     387/** 
     388 * get_term_field() - Get sanitized Term field 
     389 *  
     390 * Does checks for $term, based on the $taxonomy. The function is for 
     391 * contextual reasons and for simplicity of usage. @see sanitize_term_field() for 
     392 * more information. 
     393 * 
     394 * @package Taxonomy 
     395 * @subpackage Term 
     396 * @param string $field Term field to fetch 
     397 * @param int $term Term ID 
     398 * @param string $taxonomy Taxonomy Name 
     399 * @param string $context ?? 
     400 * @return mixed @see sanitize_term_field() 
     401 * 
     402 * @internal 
     403 *      This is all conjecture and might be partially or completely inaccurate. 
     404 */ 
    339405function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { 
    340406        $term = (int) $term; 
    341407        $term = get_term( $term, $taxonomy ); 
     
    352418        return sanitize_term_field($field, $term->$field, $term->term_id, $taxonomy, $context); 
    353419} 
    354420 
     421/** 
     422 * get_term_to_edit() - Sanitizes Term for editing 
     423 * 
     424 * Return value is @see sanitize_term() and usage is for sanitizing the term 
     425 * for editing. Function is for contextual and simplicity. 
     426 *  
     427 * @package Taxonomy 
     428 * @subpackage Term 
     429 * @param int|object $id Term ID or Object 
     430 * @param string $taxonomy Taxonomy Name 
     431 * @return mixed @see sanitize_term() 
     432 * 
     433 * @internal 
     434 *      This is all conjecture and might be partially or completely inaccurate. 
     435 */ 
    355436function get_term_to_edit( $id, $taxonomy ) { 
    356437        $term = get_term( $id, $taxonomy ); 
    357438 
     
    364445        return sanitize_term($term, $taxonomy, 'edit'); 
    365446} 
    366447 
     448/** 
     449 * get_terms() -  
     450 * 
     451 *  
     452 *  
     453 * @package Taxonomy 
     454 * @subpackage Term 
     455 * @param string|array Taxonomy name or list of Taxonomy names 
     456 * @param string|array $args ?? 
     457 * @return array List of Term Objects and their children. 
     458 * 
     459 * @internal 
     460 *      This is all conjecture and might be partially or completely inaccurate. 
     461 */ 
    367462function &get_terms($taxonomies, $args = '') { 
    368463        global $wpdb; 
    369464 
     
    535630} 
    536631 
    537632/** 
     633 * is_term() - Check if Term exists 
     634 * 
    538635 * Returns the index of a defined term, or 0 (false) if the term doesn't exist. 
     636 * 
     637 * @global $wpdb Database Object 
     638 * @param int|string $term The term to check 
     639 * @param string $taxonomy The taxonomy name to use 
     640 * @return mixed Get the term id or Term Object, if exists. 
    539641 */ 
    540642function is_term($term, $taxonomy = '') { 
    541643        global $wpdb; 
     
    558660        return $wpdb->get_row("SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE $where AND tt.taxonomy = '$taxonomy'", ARRAY_A); 
    559661} 
    560662 
     663/** 
     664 * sanitize_term() - Sanitize Term all fields 
     665 * 
     666 * Relys on @see sanitize_term_field() to sanitize the term. The difference 
     667 * is that this function will sanitize <strong>all</strong> fields. The context 
     668 * is based on @see sanitize_term_field(). 
     669 * 
     670 * The $term is expected to be either an array or an object. 
     671 * 
     672 * @param array|object $term The term to check 
     673 * @param string $taxonomy The taxonomy name to use 
     674 * @param string $context Default is display 
     675 * @return array|object Term with all fields sanitized 
     676 */ 
    561677function sanitize_term($term, $taxonomy, $context = 'display') { 
    562678        $fields = array('term_id', 'name', 'description', 'slug', 'count', 'term_group'); 
    563679 
     
    575691        return $term; 
    576692} 
    577693 
     694/** 
     695 * sanitize_term_field() -  
     696 * 
     697 * 
     698 * 
     699 * @global object $wpdb Database Object 
     700 * @param string $field Term field to sanitize 
     701 * @param string $value Search for this term value 
     702 * @param int $term_id Term ID 
     703 * @param string $taxonomy Taxonomy Name 
     704 * @param string $context Either edit, db, display, attribute, or js. 
     705 * @return mixed sanitized field 
     706 */ 
    578707function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { 
    579708        if ( 'parent' == $field  || 'term_id' == $field || 'count' == $field 
    580709                || 'term_group' == $field ) 
     
    604733        return $value; 
    605734} 
    606735 
     736/** 
     737 * wp_count_terms() - Count how many terms are in Taxonomy 
     738 * 
     739 * Default $args is 'ignore_empty' which can be @example 'ignore_empty=true' or 
     740 * @example array('ignore_empty' => true); See @see wp_parse_args() for more 
     741 * information on parsing $args. 
     742 * 
     743 * @global object $wpdb Database Object 
     744 * @param string $taxonomy Taxonomy name 
     745 * @param array|string $args Overwrite defaults 
     746 * @return int How many terms are in $taxonomy 
     747 */ 
    607748function wp_count_terms( $taxonomy, $args = array() ) { 
    608749        global $wpdb; 
    609750 
     
    618759        return $wpdb->get_var("SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE taxonomy = '$taxonomy' $where"); 
    619760} 
    620761 
     762/** 
     763 * wp_delete_object_term_relationships() -  
     764 * 
     765 * 
     766 * 
     767 * @global object $wpdb Database Object 
     768 * @param int $object_id ?? 
     769 * @param string|array $taxonomy List of Taxonomy Names or single Taxonomy name. 
     770 */ 
    621771function wp_delete_object_term_relationships( $object_id, $taxonomies ) { 
    622772        global $wpdb; 
    623773 
     
    633783                wp_update_term_count($terms, $taxonomy); 
    634784        } 
    635785 
    636         // TODO clear the cache 
     786        /** @TODO clear the cache */ 
    637787} 
    638788 
    639789/** 
    640  * Removes a term from the database. 
     790 * wp_delete_term() - Removes a term from the database. 
     791 * 
     792 * 
     793 * 
     794 * @global object $wpdb Database Object 
     795 * @param int $term Term ID 
     796 * @param string $taxonomy Taxonomy Name 
     797 * @param array|string $args Change Default 
     798 * @param bool Returns false if not term; true if completes delete action. 
    641799 */ 
    642800function wp_delete_term( $term, $taxonomy, $args = array() ) { 
    643801        global $wpdb; 
     
    691849} 
    692850 
    693851/** 
    694  * Returns the terms associated with the given object(s), in the supplied taxonomies. 
     852 * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies. 
     853 * 
     854 *  
     855 * 
     856 * @global $wpdb Database Object 
    695857 * @param int|array $object_id The id of the object(s)) to retrieve for. 
    696858 * @param string|array $taxonomies The taxonomies to retrieve terms from. 
     859 * @param array|string $args Change what is returned 
    697860 * @return array The requested term data.                         
    698861 */ 
    699862function wp_get_object_terms($object_ids, $taxonomies, $args = array()) { 
     
    748911} 
    749912 
    750913/** 
    751  * Adds a new term to the database.  Optionally marks it as an alias of an existing term. 
     914 * wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term. 
     915 * 
     916 *  
     917 * 
     918 * @global $wpdb Database Object 
    752919 * @param int|string $term The term to add or update. 
    753920 * @param string $taxonomy The taxonomy to which to add the term 
    754  * @param int|string $alias_of The id or slug of the new term's alias. 
     921 * @param array|string $args Change the values of the inserted term 
     922 * @return array The Term ID and Term Taxonomy ID 
    755923 */ 
    756924function wp_insert_term( $term, $taxonomy, $args = array() ) { 
    757925        global $wpdb; 
     
    818986} 
    819987 
    820988/** 
     989 * wp_set_object_terms() -  
     990 *  
    821991 * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy 
    822992 * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug). 
     993 * 
     994 * @global $wpdb Database Object 
    823995 * @param int $object_id The object to relate to. 
    824996 * @param array|int|string $term The slug or id of the term. 
    825997 * @param array|string $taxonomy The context in which to relate the term to the object. 
     998 * @param bool $append If false will delete difference of terms. 
    826999 */ 
    8271000function wp_set_object_terms($object_id, $terms, $taxonomy, $append = false) { 
    8281001        global $wpdb; 
     
    11201293        } 
    11211294} 
    11221295 
    1123 ?> 
    1124  No newline at end of file 
     1296?>