WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.6159.phpdoc.patch

File taxonomy.6159.phpdoc.patch, 17.5 KB (added by darkdragon, 7 years ago)

More phpDoc for revision 6159, still incomplete.

  • taxonomy.php

     
    11<?php 
     2/** 
     3 * @package WordPress 
     4 * @subpackage Taxonomy 
     5 * @since 2.3 
     6 */ 
    27 
    38// 
    49// Taxonomy Registration 
    510// 
    611 
    712/** 
    8  * @global array $wp_taxonomies Fill me out please 
     13 * @global array $wp_taxonomies Default Taxonomy Objects 
    914 */ 
    1015$wp_taxonomies = array(); 
    1116$wp_taxonomies['category'] = (object) array('name' => 'category', 'object_type' => 'post', 'hierarchical' => true, 'update_count_callback' => '_update_post_term_count'); 
     
    2530 *      'post_tag' 
    2631 *      )</pre> 
    2732 * 
    28  * @package Taxonomy 
     33 * @package WordPress 
     34 * @subpackage Taxonomy 
     35 *  
    2936 * @global array $wp_taxonomies 
    3037 * @param string $object_type Name of the type of taxonomy object 
    3138 * @return array The names of all within the object_type. 
     
    5158 * The get_taxonomy function will first check that the parameter string given 
    5259 * is a taxonomy object and if it is, it will return it. 
    5360 * 
    54  * @package Taxonomy 
     61 * @package WordPress 
     62 * @subpackage Taxonomy 
     63 *  
    5564 * @global array $wp_taxonomies 
    5665 * @param string $taxonomy Name of taxonomy object to return 
    5766 * @return object|bool The Taxonomy Object or false if taxonomy doesn't exist 
     
    7180/** 
    7281 * is_taxonomy() - Checks that the taxonomy name exists 
    7382 * 
    74  * @package Taxonomy 
     83 * @package WordPress 
     84 * @subpackage Taxonomy 
     85 *  
    7586 * @global array $wp_taxonomies 
    7687 * @param string $taxonomy Name of taxonomy object 
    7788 * @return bool Whether the taxonomy exists or not. 
     
    91102 * Checks to make sure that the taxonomy is an object first. Then Gets the object, and finally 
    92103 * returns the hierarchical value in the object. 
    93104 * 
    94  * A false return value, might also mean that the taxonomy does not exist. 
     105 * A false return value might also mean that the taxonomy does not exist. 
    95106 * 
    96  * @package Taxonomy 
     107 * @package WordPress 
     108 * @subpackage Taxonomy 
     109 *  
    97110 * @global array $wp_taxonomies 
    98111 * @param string $taxonomy Name of taxonomy object 
    99112 * @return bool Whether the taxonomy is hierarchical 
     
    125138 * update_count_callback works much like a hook, in that it will be called (or something from 
    126139 *      somewhere). 
    127140 * 
    128  * @package Taxonomy 
     141 * @package WordPress 
     142 * @subpackage Taxonomy 
     143 *  
    129144 * @global array $wp_taxonomies 
    130145 * @param string $taxonomy Name of taxonomy object 
    131146 * @param string $object_type Name of the object type for the taxonomy object. 
     
    164179 * functions or using the database by using $args with either ASC or DESC array. The value should 
    165180 * be in the key named 'order'. 
    166181 * 
    167  * @package Taxonomy 
    168  * @subpackage Term 
     182 * @package WordPress 
     183 * @subpackage Taxonomy 
     184 * @category Term  
     185 * 
    169186 * @global object $wpdb Database Query 
    170187 * @param string|array $terms String of term or array of string values of terms that will be used 
    171188 * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names 
     
    209226} 
    210227 
    211228/** 
    212  * get_term() - 
     229 * get_term() - Get all Term data from database by Term ID. 
    213230 * 
     231 * The usage of the get_term function is to apply filters to a term object. 
     232 * It is possible to get a term object from the database before applying the 
     233 * filters.  
    214234 * 
     235 * $term ID must be part of $taxonomy, to get from the database. Failure, might be 
     236 * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the 
     237 * get_row method. 
    215238 * 
    216  * @package Taxonomy 
    217  * @subpackage Term 
     239 * There are two hooks, one is specifically for each term, named 'get_term', and the second is  
     240 * for the taxonomy name. Both hooks gets the term object, and the taxonomy name as parameters. 
     241 * Both hooks are expected to return a Term object. 
     242 * 
     243 * @package WordPress 
     244 * @subpackage Taxonomy 
     245 * @category Term  
     246 * 
    218247 * @global object $wpdb Database Query 
    219  * @param int|object $term 
    220  * @param string $taxonomy 
    221  * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N 
     248 * @param int|object $term If integer, will get from database. If object will apply filters and return $term. 
     249 * @param string $taxonomy Taxonomy name that $term is part of. 
     250 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
     251 * @param string $filter  
    222252 * @return mixed Term Row from database 
    223253 * 
    224254 * @internal 
    225  *      This won't appear but just a note to say that this is all conjecture and parts or whole 
    226  *      might be inaccurate or wrong. 
     255 *   This is all conjecture and might be partially or completely inaccurate. 
     256 *   Uses custom hook phpdoc documentation that isn't compatible with phpDoc. Useful for a custom 
     257 *   solution if used in an uniform fashion throughout the code base. 
    227258 */ 
    228259function &get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') { 
    229260        global $wpdb; 
     
    247278         
    248279        /** 
    249280         * @internal 
    250          * Filter tag is basically: filter 'type' 'hook_name' 'description' 
    251281         * 
    252282         * Takes two parameters the term Object and the taxonomy name. Must return term object. 
    253          * @filter object get_term Used in @see get_term() as a catch-all filter for every $term 
     283         * Used in @see get_term() as a catch-all filter for every $term. 
     284         *  
     285         * @hook-name get_term 
     286         * @hook-return object 
     287         * @hook-param object $_term The current term object 
     288         * @hook-param string $taxonomy What taxonomy the term is in. 
    254289         */ 
    255290        $_term = apply_filters('get_term', $_term, $taxonomy); 
     291         
    256292        /** 
    257293         * @internal 
    258          * Filter tag is basically: filter 'type' 'hook_name' 'description' 
    259294         * 
    260295         * Takes two parameters the term Object and the taxonomy name. Must return term object. 
    261296         * $taxonomy will be the taxonomy name, so for example, if 'category', it would be 'get_category' 
    262297         * as the filter name. 
     298         * 
    263299         * Useful for custom taxonomies or plugging into default taxonomies. 
    264          * @filter object get_$taxonomy Used in @see get_term() as specific filter for each $taxonomy. 
     300         *  
     301         * @hook-name get_$taxonomy 
     302         * @hook-return object 
     303         * @hook-param object $_term The current term object 
     304         * @hook-param string $taxonomy What taxonomy the term is in. 
    265305         */ 
    266306        $_term = apply_filters("get_$taxonomy", $_term, $taxonomy); 
    267307        $_term = sanitize_term($_term, $taxonomy, $filter); 
     
    278318} 
    279319 
    280320/** 
    281  * get_term_by() - 
     321 * get_term_by() - Get all Term data from database by Term field and data. 
    282322 * 
     323 * Warning: $value is not escaped for 'name' $field. You must do it yourself, if required. 
    283324 * 
     325 * The default $field is 'id', therefore it is possible to also use null for field, but not 
     326 * recommended that you do so. 
    284327 * 
    285  * @package Taxonomy 
    286  * @subpackage Term 
     328 * If $value does not exist, the return value will be false. If $taxonomy exists and $field 
     329 * and $value combinations exist, the Term will be returned. 
     330 *  
     331 * 
     332 * @package WordPress 
     333 * @subpackage Taxonomy 
     334 * @category Term  
     335 * 
    287336 * @global object $wpdb Database Query 
    288  * @param string $field 
    289  * @param string $value 
    290  * @param string $taxonomy 
    291  * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N 
     337 * @param string $field Either 'slug', 'name', or 'id' 
     338 * @param string|int $value Search for this term value 
     339 * @param string $taxonomy Taxonomy Name 
     340 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
     341 * @param string $filter  
    292342 * @return mixed Term Row from database 
    293343 * 
    294344 * @internal 
    295  *      This won't appear but just a note to say that this is all conjecture and parts or whole 
    296  *      might be inaccurate or wrong. 
     345 *      This is all conjecture and might be partially or completely inaccurate. 
    297346 */ 
    298347function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') { 
    299348        global $wpdb; 
     
    341390 * 
    342391 * Only useful for taxonomies which are hierarchical. 
    343392 *  
    344  * @package Taxonomy 
    345  * @subpackage Term 
     393 * @package WordPress 
     394 * @subpackage Taxonomy 
     395 * @category Term  
     396 * 
    346397 * @global object $wpdb Database Query 
    347398 * @param string $term Name of Term to get children 
    348399 * @param string $taxonomy Taxonomy Name 
     
    377428 * contextual reasons and for simplicity of usage. @see sanitize_term_field() for 
    378429 * more information. 
    379430 * 
    380  * @package Taxonomy 
    381  * @subpackage Term 
     431 * @package WordPress 
     432 * @subpackage Taxonomy 
     433 * @category Term  
     434 * 
    382435 * @param string $field Term field to fetch 
    383436 * @param int $term Term ID 
    384437 * @param string $taxonomy Taxonomy Name 
     
    409462 * Return value is @see sanitize_term() and usage is for sanitizing the term 
    410463 * for editing. Function is for contextual and simplicity. 
    411464 *  
    412  * @package Taxonomy 
    413  * @subpackage Term 
     465 * @package WordPress 
     466 * @subpackage Taxonomy 
     467 * @category Term  
     468 * 
    414469 * @param int|object $id Term ID or Object 
    415470 * @param string $taxonomy Taxonomy Name 
    416471 * @return mixed @see sanitize_term() 
     
    435490 * 
    436491 *  
    437492 *  
    438  * @package Taxonomy 
    439  * @subpackage Term 
     493 * @package WordPress 
     494 * @subpackage Taxonomy 
     495 * @category Term  
     496 * 
    440497 * @param string|array Taxonomy name or list of Taxonomy names 
    441498 * @param string|array $args ?? 
    442499 * @return array List of Term Objects and their children. 
     
    622679 * 
    623680 * Returns the index of a defined term, or 0 (false) if the term doesn't exist. 
    624681 * 
     682 * @package WordPress 
     683 * @subpackage Taxonomy 
     684 * @category Term  
     685 * 
    625686 * @global $wpdb Database Object 
    626687 * @param int|string $term The term to check 
    627688 * @param string $taxonomy The taxonomy name to use 
     
    657718 * 
    658719 * The $term is expected to be either an array or an object. 
    659720 * 
     721 * @package WordPress 
     722 * @subpackage Taxonomy 
     723 * @category Term  
     724 * 
    660725 * @param array|object $term The term to check 
    661726 * @param string $taxonomy The taxonomy name to use 
    662727 * @param string $context Default is display 
     
    684749 * 
    685750 * 
    686751 * 
     752 * @package WordPress 
     753 * @subpackage Taxonomy 
     754 * @category Term  
     755 * 
    687756 * @global object $wpdb Database Object 
    688757 * @param string $field Term field to sanitize 
    689758 * @param string $value Search for this term value 
     
    735804 * @example array('ignore_empty' => true); See @see wp_parse_args() for more 
    736805 * information on parsing $args. 
    737806 * 
     807 * @package WordPress 
     808 * @subpackage Taxonomy 
     809 * @category Term  
     810 * 
    738811 * @global object $wpdb Database Object 
    739812 * @param string $taxonomy Taxonomy name 
    740813 * @param array|string $args Overwrite defaults 
     
    759832 * 
    760833 * 
    761834 * 
     835 * @package WordPress 
     836 * @subpackage Taxonomy 
     837 * @category Term  
     838 * 
    762839 * @global object $wpdb Database Object 
    763840 * @param int $object_id ?? 
    764841 * @param string|array $taxonomy List of Taxonomy Names or single Taxonomy name. 
     
    780857} 
    781858 
    782859/** 
    783  * Removes a term from the database. 
     860 * wp_delete_term() - Removes a term from the database. 
     861 * 
     862 * 
     863 * 
     864 * @package WordPress 
     865 * @subpackage Taxonomy 
     866 * @category Term  
     867 * 
     868 * @global object $wpdb Database Object 
     869 * @param int $term Term ID 
     870 * @param string $taxonomy Taxonomy Name 
     871 * @param array|string $args Change Default 
     872 * @param bool Returns false if not term; true if completes delete action. 
    784873 */ 
    785874function wp_delete_term( $term, $taxonomy, $args = array() ) { 
    786875        global $wpdb; 
     
    837926} 
    838927 
    839928/** 
    840  * Returns the terms associated with the given object(s), in the supplied taxonomies. 
     929 * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies. 
     930 * 
     931 *  
     932 * 
     933 * @package WordPress 
     934 * @subpackage Taxonomy 
     935 * @category Term  
     936 * 
     937 * @global $wpdb Database Object 
    841938 * @param int|array $object_id The id of the object(s)) to retrieve for. 
    842939 * @param string|array $taxonomies The taxonomies to retrieve terms from. 
    843  * @return array The requested term data. 
     940 * @param array|string $args Change what is returned 
     941 * @return array The requested term data.                         
    844942 */ 
    845943function wp_get_object_terms($object_ids, $taxonomies, $args = array()) { 
    846944        global $wpdb; 
     
    900998 * 
    901999 *  
    9021000 * 
     1001 * @package WordPress 
     1002 * @subpackage Taxonomy 
     1003 * @category Term  
     1004 * 
    9031005 * @global $wpdb Database Object 
    9041006 * @param int|string $term The term to add or update. 
    9051007 * @param string $taxonomy The taxonomy to which to add the term 
     
    9811083 * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy 
    9821084 * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug). 
    9831085 * 
     1086 * @package WordPress 
     1087 * @subpackage Taxonomy 
     1088 * @category Term  
     1089 * 
    9841090 * @global $wpdb Database Object 
    9851091 * @param int $object_id The object to relate to. 
    9861092 * @param array|int|string $term The slug or id of the term. 
    9871093 * @param array|string $taxonomy The context in which to relate the term to the object. 
    9881094 * @param bool $append If false will delete difference of terms. 
     1095 * @return array Affected Term IDs 
    9891096 */ 
    9901097function wp_set_object_terms($object_id, $terms, $taxonomy, $append = false) { 
    9911098        global $wpdb; 
     
    10301137        return $tt_ids; 
    10311138} 
    10321139 
     1140/** 
     1141 * wp_unique_term_slug() - Will make @see $slug unique, if it isn't already 
     1142 *  
     1143 * The @see $slug has to be unique global to every taxonomy, meaning that one taxonomy 
     1144 * term can't have a matching slug with another taxonomy term. Each slug has to be 
     1145 * globally unique for every taxonomy. 
     1146 * 
     1147 * The way this works is that if the taxonomy that the term belongs to is heirarchical 
     1148 * and has a parent, it will append that parent to the @see $slug. 
     1149 * 
     1150 * If that still doesn't return an unique slug, then it try to append a number until 
     1151 * it finds a number that is truely unique. 
     1152 *  
     1153 * The only purpose for @see $term is for appending a parent, if one exists. 
     1154 * 
     1155 * @package WordPress 
     1156 * @subpackage Taxonomy 
     1157 * @category Term 
     1158 * 
     1159 * @global $wpdb Database Object 
     1160 * @param string $slug The string that will be tried for a unique slug 
     1161 * @param object $term The term object that the $slug will belong too 
     1162 * @return string Will return a true unique slug. 
     1163 */ 
    10331164function wp_unique_term_slug($slug, $term) { 
    10341165        global $wpdb; 
    10351166 
     
    10621193        return $slug; 
    10631194} 
    10641195 
     1196/** 
     1197 * wp_update_term() -  
     1198 *  
     1199 *  
     1200 * 
     1201 * @package WordPress 
     1202 * @subpackage Taxonomy 
     1203 * @category Term  
     1204 * 
     1205 * @global $wpdb Database Object 
     1206 * @param int $term The ID of the term 
     1207 * @param string $taxonomy The context in which to relate the term to the object. 
     1208 * @param array|string $args Overwrite defaults 
     1209 * @return array Returns Term ID and Taxonomy Term ID 
     1210 */ 
    10651211function wp_update_term( $term, $taxonomy, $args = array() ) { 
    10661212        global $wpdb; 
    10671213 
     
    11371283        return array('term_id' => $term_id, 'term_taxonomy_id' => $tt_id); 
    11381284} 
    11391285 
     1286/** 
     1287 * wp_update_term_count() - Updates the amount of terms in taxonomy 
     1288 *  
     1289 * If there is a taxonomy callback applyed, then it will be called for updating the count. 
     1290 * 
     1291 * The default action is to count what the amount of terms have the relationship of term ID. 
     1292 * Once that is done, then update the database. 
     1293 * 
     1294 * @package WordPress 
     1295 * @subpackage Taxonomy 
     1296 * @category Term  
     1297 * 
     1298 * @global $wpdb Database Object 
     1299 * @param int|array $terms The ID of the terms 
     1300 * @param string $taxonomy The context of the term. 
     1301 * @return bool If no terms will return false, and if successful will return true. 
     1302 */ 
    11401303function wp_update_term_count( $terms, $taxonomy ) { 
    11411304        global $wpdb; 
    11421305 
     
    11691332// Cache 
    11701333// 
    11711334 
     1335/** 
     1336 * clean_object_term_cache() -  
     1337 *  
     1338 *  
     1339 * 
     1340 * @package WordPress 
     1341 * @subpackage Taxonomy 
     1342 * @category Cache  
     1343 * 
     1344 * @global $object_term_cache  
     1345 * @global $blog_id The id of the blog, in case there is more than one blog using the library. 
     1346 * @param int|array $object_ids  
     1347 * @param string $object_type @see get_object_taxonomies 
     1348 * @return null 
     1349 */ 
    11721350function clean_object_term_cache($object_ids, $object_type) { 
    11731351        global $object_term_cache, $blog_id; 
    11741352 
     
    11851363        } 
    11861364} 
    11871365 
     1366/** 
     1367 * clean_term_cache() -  
     1368 *  
     1369 *  
     1370 * 
     1371 * @package WordPress 
     1372 * @subpackage Taxonomy 
     1373 * @category Cache  
     1374 * 
     1375 * @global $object_term_cache  
     1376 * @global $blog_id The id of the blog, in case there is more than one blog using the library. 
     1377 * @param int|array $ids  
     1378 * @param string $taxonomy Can be empty and will assume tt_ids, else will use for context. 
     1379 * @return null 
     1380 */ 
    11881381function clean_term_cache($ids, $taxonomy = '') { 
    11891382        global $wpdb; 
    11901383 
     
    12961489        return $children; 
    12971490} 
    12981491 
     1492/** 
     1493 * @access private 
     1494 * _get_term_children() - Get array of child terms 
     1495 *  
     1496 * If $terms is an array of objects, then objects will returned from the function. 
     1497 * If $terms is an array of IDs, then an array of ids of children will be returned. 
     1498 * 
     1499 * @package WordPress 
     1500 * @subpackage Taxonomy 
     1501 * 
     1502 * @param int $term_id Look for this Term ID in $terms 
     1503 * @param array $terms List of Term IDs 
     1504 * @param string $taxonomy Term Context 
     1505 * @return array  
     1506 */ 
    12991507function &_get_term_children($term_id, $terms, $taxonomy) { 
    13001508        if ( empty($terms) ) 
    13011509                return array(); 
     
    13351543        return $term_list; 
    13361544} 
    13371545 
    1338 // Recalculates term counts by including items from child terms 
    1339 // Assumes all relevant children are already in the $terms argument 
     1546/** 
     1547 * @access private 
     1548 * _pad_term_counts() - Add count of children to parent count 
     1549 *  
     1550 * Recalculates term counts by including items from child terms. 
     1551 * Assumes all relevant children are already in the $terms argument 
     1552 * 
     1553 * @package WordPress 
     1554 * @subpackage Taxonomy 
     1555 * 
     1556 * @param array $terms List of Term IDs 
     1557 * @param string $taxonomy Term Context 
     1558 */ 
    13401559function _pad_term_counts(&$terms, $taxonomy) { 
    13411560        global $wpdb; 
    13421561 
     
    13841603// Default callbacks 
    13851604// 
    13861605 
     1606/** 
     1607 * @access private 
     1608 * _update_post_term_count() - Will update term count based on posts 
     1609 *  
     1610 * Private function for the default callback for post_tag and category taxonomies. 
     1611 * 
     1612 * @package WordPress 
     1613 * @subpackage Taxonomy 
     1614 * @category Callback  
     1615 * 
     1616 * @global $wpdb Database Object 
     1617 * @param array $terms List of Term IDs 
     1618 */ 
    13871619function _update_post_term_count( $terms ) { 
    13881620        global $wpdb; 
    13891621