WordPress.org
Get WordPress

Make WordPress Core

Ticket #4742: taxonomy.6159.phpdoc.patch

File taxonomy.6159.phpdoc.patch, 17.5 KB (added by darkdragon, 18 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