WordPress.org

Make WordPress Core

Changeset 6092


Ignore:
Timestamp:
09/12/07 02:56:44 (7 years ago)
Author:
ryan
Message:

More phpdoc for taxonomy from darkdragon. see #4742

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/taxonomy.php

    r6087 r6092  
    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 
     
    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) { 
     
    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 ) { 
     
    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 ) { 
     
    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. 
     93 * 
     94 * A false return value, might also mean that the taxonomy does not exist. 
    9695 * 
    9796 * @package Taxonomy 
     
    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) { 
     
    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 
     
    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() ) { 
     
    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 
     
    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() ) { 
     
    249245        } 
    250246    } 
    251  
     247     
     248    /** 
     249     * @internal 
     250     * Filter tag is basically: filter 'type' 'hook_name' 'description' 
     251     * 
     252     * 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 
     254     */ 
    252255    $_term = apply_filters('get_term', $_term, $taxonomy); 
     256    /** 
     257     * @internal 
     258     * Filter tag is basically: filter 'type' 'hook_name' 'description' 
     259     * 
     260     * Takes two parameters the term Object and the taxonomy name. Must return term object. 
     261     * $taxonomy will be the taxonomy name, so for example, if 'category', it would be 'get_category' 
     262     * as the filter name. 
     263     * 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. 
     265     */ 
    253266    $_term = apply_filters("get_$taxonomy", $_term, $taxonomy); 
    254267    $_term = sanitize_term($_term, $taxonomy, $filter); 
     
    321334} 
    322335 
     336/** 
     337 * get_term_children() - Merge all term children into a single array. 
     338 * 
     339 * This recursive function will merge all of the children of $term into 
     340 * the same array. 
     341 * 
     342 * Only useful for taxonomies which are hierarchical. 
     343 *  
     344 * @package Taxonomy 
     345 * @subpackage Term 
     346 * @global object $wpdb Database Query 
     347 * @param string $term Name of Term to get children 
     348 * @param string $taxonomy Taxonomy Name 
     349 * @return array List of Term Objects 
     350 * 
     351 * @internal 
     352 *      This is all conjecture and might be partially or completely inaccurate. 
     353 */ 
    323354function get_term_children( $term, $taxonomy ) { 
    324355    if ( ! is_taxonomy($taxonomy) ) 
     
    340371} 
    341372 
     373/** 
     374 * get_term_field() - Get sanitized Term field 
     375 *  
     376 * Does checks for $term, based on the $taxonomy. The function is for 
     377 * contextual reasons and for simplicity of usage. @see sanitize_term_field() for 
     378 * more information. 
     379 * 
     380 * @package Taxonomy 
     381 * @subpackage Term 
     382 * @param string $field Term field to fetch 
     383 * @param int $term Term ID 
     384 * @param string $taxonomy Taxonomy Name 
     385 * @param string $context ?? 
     386 * @return mixed @see sanitize_term_field() 
     387 * 
     388 * @internal 
     389 *      This is all conjecture and might be partially or completely inaccurate. 
     390 */ 
    342391function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { 
    343392    $term = (int) $term; 
     
    356405} 
    357406 
     407/** 
     408 * get_term_to_edit() - Sanitizes Term for editing 
     409 * 
     410 * Return value is @see sanitize_term() and usage is for sanitizing the term 
     411 * for editing. Function is for contextual and simplicity. 
     412 *  
     413 * @package Taxonomy 
     414 * @subpackage Term 
     415 * @param int|object $id Term ID or Object 
     416 * @param string $taxonomy Taxonomy Name 
     417 * @return mixed @see sanitize_term() 
     418 * 
     419 * @internal 
     420 *      This is all conjecture and might be partially or completely inaccurate. 
     421 */ 
    358422function get_term_to_edit( $id, $taxonomy ) { 
    359423    $term = get_term( $id, $taxonomy ); 
     
    368432} 
    369433 
     434/** 
     435 * get_terms() -  
     436 * 
     437 *  
     438 *  
     439 * @package Taxonomy 
     440 * @subpackage Term 
     441 * @param string|array Taxonomy name or list of Taxonomy names 
     442 * @param string|array $args ?? 
     443 * @return array List of Term Objects and their children. 
     444 * 
     445 * @internal 
     446 *      This is all conjecture and might be partially or completely inaccurate. 
     447 */ 
    370448function &get_terms($taxonomies, $args = '') { 
    371449    global $wpdb; 
     
    542620 
    543621/** 
     622 * is_term() - Check if Term exists 
     623 * 
    544624 * Returns the index of a defined term, or 0 (false) if the term doesn't exist. 
     625 * 
     626 * @global $wpdb Database Object 
     627 * @param int|string $term The term to check 
     628 * @param string $taxonomy The taxonomy name to use 
     629 * @return mixed Get the term id or Term Object, if exists. 
    545630 */ 
    546631function is_term($term, $taxonomy = '') { 
     
    565650} 
    566651 
     652/** 
     653 * sanitize_term() - Sanitize Term all fields 
     654 * 
     655 * Relys on @see sanitize_term_field() to sanitize the term. The difference 
     656 * is that this function will sanitize <strong>all</strong> fields. The context 
     657 * is based on @see sanitize_term_field(). 
     658 * 
     659 * The $term is expected to be either an array or an object. 
     660 * 
     661 * @param array|object $term The term to check 
     662 * @param string $taxonomy The taxonomy name to use 
     663 * @param string $context Default is display 
     664 * @return array|object Term with all fields sanitized 
     665 */ 
    567666function sanitize_term($term, $taxonomy, $context = 'display') { 
    568667    $fields = array('term_id', 'name', 'description', 'slug', 'count', 'parent', 'term_group'); 
     
    582681} 
    583682 
     683/** 
     684 * sanitize_term_field() -  
     685 * 
     686 * 
     687 * 
     688 * @global object $wpdb Database Object 
     689 * @param string $field Term field to sanitize 
     690 * @param string $value Search for this term value 
     691 * @param int $term_id Term ID 
     692 * @param string $taxonomy Taxonomy Name 
     693 * @param string $context Either edit, db, display, attribute, or js. 
     694 * @return mixed sanitized field 
     695 */ 
    584696function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) { 
    585697    if ( 'parent' == $field  || 'term_id' == $field || 'count' == $field 
     
    614726} 
    615727 
     728/** 
     729 * wp_count_terms() - Count how many terms are in Taxonomy 
     730 * 
     731 * Default $args is 'ignore_empty' which can be @example 'ignore_empty=true' or 
     732 * @example array('ignore_empty' => true); See @see wp_parse_args() for more 
     733 * information on parsing $args. 
     734 * 
     735 * @global object $wpdb Database Object 
     736 * @param string $taxonomy Taxonomy name 
     737 * @param array|string $args Overwrite defaults 
     738 * @return int How many terms are in $taxonomy 
     739 */ 
    616740function wp_count_terms( $taxonomy, $args = array() ) { 
    617741    global $wpdb; 
     
    628752} 
    629753 
     754/** 
     755 * wp_delete_object_term_relationships() -  
     756 * 
     757 * 
     758 * 
     759 * @global object $wpdb Database Object 
     760 * @param int $object_id ?? 
     761 * @param string|array $taxonomy List of Taxonomy Names or single Taxonomy name. 
     762 */ 
    630763function wp_delete_object_term_relationships( $object_id, $taxonomies ) { 
    631764    global $wpdb; 
     
    757890 
    758891/** 
    759  * Adds a new term to the database.  Optionally marks it as an alias of an existing term. 
     892 * wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term. 
     893 * 
     894 *  
     895 * 
     896 * @global $wpdb Database Object 
    760897 * @param int|string $term The term to add or update. 
    761898 * @param string $taxonomy The taxonomy to which to add the term 
    762  * @param int|string $alias_of The id or slug of the new term's alias. 
     899 * @param array|string $args Change the values of the inserted term 
     900 * @return array The Term ID and Term Taxonomy ID 
    763901 */ 
    764902function wp_insert_term( $term, $taxonomy, $args = array() ) { 
     
    825963 
    826964/** 
     965 * wp_set_object_terms() -  
     966 *  
    827967 * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy 
    828968 * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug). 
     969 * 
     970 * @global $wpdb Database Object 
    829971 * @param int $object_id The object to relate to. 
    830972 * @param array|int|string $term The slug or id of the term. 
    831973 * @param array|string $taxonomy The context in which to relate the term to the object. 
     974 * @param bool $append If false will delete difference of terms. 
    832975 */ 
    833976function wp_set_object_terms($object_id, $terms, $taxonomy, $append = false) { 
Note: See TracChangeset for help on using the changeset viewer.