WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.phpdoc.r5900.diff

File taxonomy.phpdoc.r5900.diff, 16.7 KB (added by darkdragon, 7 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?>