WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.r6291.phpdoc.patch

File taxonomy.r6291.phpdoc.patch, 12.1 KB (added by darkdragon, 8 years ago)

Patched against r6291 and cleans up and brings the total needing documentation to four

  • taxonomy.php

     
    235235 * name as parameters. Both hooks are expected to return a Term object. 
    236236 * 
    237237 * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    238  * term object. Used in @see get_term() as a catch-all filter for every $term. 
     238 * term object. Used in get_term() as a catch-all filter for every $term. 
    239239 * 
    240240 * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy name. Must return 
    241241 * term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be 
     
    246246 * @since 2.3 
    247247 * 
    248248 * @uses $wpdb 
     249 * @uses sanitize_term() Cleanses the term based on $filter context before returning. 
     250 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param. 
    249251 * 
    250252 * @param int|object $term If integer, will get from database. If object will apply filters and return $term. 
    251253 * @param string $taxonomy Taxonomy name that $term is part of. 
    252254 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
    253  * @param string $filter {@internal Missing Description}} 
     255 * @param string $filter Optional, default is raw or no WordPress defined filter will applied. 
    254256 * @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not 
    255257 * exist then WP_Error will be returned. 
    256258 */ 
     
    305307 * @since 2.3 
    306308 * 
    307309 * @uses $wpdb 
     310 * @uses sanitize_term() Cleanses the term based on $filter context before returning. 
     311 * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param. 
    308312 * 
    309313 * @param string $field Either 'slug', 'name', or 'id' 
    310314 * @param string|int $value Search for this term value 
    311315 * @param string $taxonomy Taxonomy Name 
    312316 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N 
    313  * @param string $filter {@internal Missing Description}} 
     317 * @param string $filter Optional, default is raw or no WordPress defined filter will applied. 
    314318 * @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found. 
    315319 */ 
    316320function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') { 
     
    394398 * get_term_field() - Get sanitized Term field 
    395399 *  
    396400 * Does checks for $term, based on the $taxonomy. The function is for 
    397  * contextual reasons and for simplicity of usage. @see sanitize_term_field() for 
     401 * contextual reasons and for simplicity of usage. See sanitize_term_field() for 
    398402 * more information. 
    399403 * 
    400404 * @package WordPress 
     
    406410 * @param string $field Term field to fetch 
    407411 * @param int $term Term ID 
    408412 * @param string $taxonomy Taxonomy Name 
    409  * @param string $context {@internal Missing Description}} 
     413 * @param string $context Optional, default is display. Look at sanitize_term_field() for available options. 
    410414 * @return mixed Will return an empty string if $term is not an object or if $field is not set in $term. 
    411415 */ 
    412416function get_term_field( $field, $term, $taxonomy, $context = 'display' ) { 
     
    427431/** 
    428432 * get_term_to_edit() - Sanitizes Term for editing 
    429433 * 
    430  * Return value is @see sanitize_term() and usage is for sanitizing the term 
     434 * Return value is sanitize_term() and usage is for sanitizing the term 
    431435 * for editing. Function is for contextual and simplicity. 
    432436 *  
    433437 * @package WordPress 
     
    713717/** 
    714718 * sanitize_term() - Sanitize Term all fields 
    715719 * 
    716  * Relys on @see sanitize_term_field() to sanitize the term. The difference 
     720 * Relys on sanitize_term_field() to sanitize the term. The difference 
    717721 * is that this function will sanitize <strong>all</strong> fields. The context 
    718  * is based on @see sanitize_term_field(). 
     722 * is based on sanitize_term_field(). 
    719723 * 
    720724 * The $term is expected to be either an array or an object. 
    721725 * 
     
    748752} 
    749753 
    750754/** 
    751  * sanitize_term_field() - {@internal Missing Short Description}} 
     755 * sanitize_term_field() - Cleanse the field value in the term based on the context 
    752756 * 
    753  * {@internal Missing Long Description}} 
     757 * Passing a term field value through the function should be assumed to have cleansed 
     758 * the value for whatever context the term field is going to be used. 
    754759 * 
     760 * If no context or an unsupported context is given, then default filters will be applied. 
     761 * 
     762 * There are enough filters for each context to support a custom filtering without creating 
     763 * your own filter function. Simply create a function that hooks into the filter you need. 
     764 * 
    755765 * @package WordPress 
    756766 * @subpackage Taxonomy 
    757767 * @since 2.3 
     
    834844} 
    835845 
    836846/** 
    837  * wp_delete_object_term_relationships() - {@internal Missing Short Description}} 
     847 * wp_delete_object_term_relationships() - Will unlink the term from the taxonomy 
    838848 * 
    839  * {@internal Missing Long Description}} 
     849 * Will remove the term's relationship to the taxonomy, not the term or taxonomy itself. 
     850 * The term and taxonomy will still exist. Will require the term's object ID to perform 
     851 * the operation. 
    840852 * 
    841853 * @package WordPress 
    842854 * @subpackage Taxonomy 
     
    865877/** 
    866878 * wp_delete_term() - Removes a term from the database. 
    867879 * 
    868  * {@internal Missing Long Description}} 
     880 * If the term is a parent of other terms, then the children will be updated 
     881 * to that term's parent. 
    869882 * 
     883 * The $args 'default' will only override the terms found, if there is only one 
     884 * term found. Any other and the found terms are used. 
     885 * 
    870886 * @package WordPress 
    871887 * @subpackage Taxonomy 
    872888 * @since 2.3 
     889 * 
    873890 * @uses $wpdb 
     891 * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action hooks, 
     892 *      passing term object, term id. 'delete_term' gets an additional parameter with 
     893 *      the $taxonomy parameter. 
    874894 * 
    875895 * @param int $term Term ID 
    876896 * @param string $taxonomy Taxonomy Name 
    877  * @param array|string $args Change Default 
    878  * @return bool Returns false if not term; true if completes delete action. 
     897 * @param array|string $args Optional. Change 'default' term id and override found term ids. 
     898 * @return bool|WP_Error Returns false if not term; true if completes delete action. 
    879899 */ 
    880900function wp_delete_term( $term, $taxonomy, $args = array() ) { 
    881901        global $wpdb; 
     
    933953} 
    934954 
    935955/** 
    936  * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies. 
     956 * wp_get_object_terms() - Retrieves the terms associated with the given object(s), in the supplied taxonomies. 
    937957 * 
    938958 * {@internal Missing Long Description}} 
    939959 * 
     
    942962 * @since 2.3 
    943963 * @uses $wpdb 
    944964 * 
    945  * @param int|array $object_id The id of the object(s)) to retrieve. 
     965 * @param int|array $object_id The id of the object(s) to retrieve. 
    946966 * @param string|array $taxonomies The taxonomies to retrieve terms from. 
    947967 * @param array|string $args Change what is returned 
    948968 * @return array|WP_Error The requested term data or empty array if no terms found. WP_Error if $taxonomy does not exist. 
     
    10881108} 
    10891109 
    10901110/** 
    1091  * wp_set_object_terms() - {@internal Missing Short Description}} 
     1111 * wp_set_object_terms() - Create Term and Taxonomy Relationships 
    10921112 *  
    1093  * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy 
    1094  * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug). 
     1113 * Relates an object (post, link etc) to a term and taxonomy type. Creates the term and taxonomy 
     1114 * relationship if it doesn't already exist. Creates a term if it doesn't exist (using the slug). 
    10951115 * 
     1116 * A relationship means that the term is grouped in or belongs to the taxonomy. A term has no 
     1117 * meaning until it is given context by defining which taxonomy it exists under. 
     1118 * 
    10961119 * @package WordPress 
    10971120 * @subpackage Taxonomy 
    10981121 * @since 2.3 
     
    12061229} 
    12071230 
    12081231/** 
    1209  * wp_update_term() - {@internal Missing Short Description}} 
     1232 * wp_update_term() - Update term based on arguments provided 
    12101233 * 
    1211  * {@internal Missing Long Description}} 
     1234 * The $args will indiscriminately override all values with the same field name. Care 
     1235 * must be taken to not override important information need to update or update will 
     1236 * fail (or perhaps create a new term, neither would be acceptable). 
    12121237 * 
     1238 * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not defined 
     1239 * in $args already. 
     1240 * 
     1241 * 'alias_of' will create a term group, if it doesn't already exist, and update it for 
     1242 * the $term. 
     1243 * 
     1244 * If the 'slug' argument in $args is missing, then the 'name' in $args will be used. 
     1245 * It should also be noted that if you set 'slug' and it isn't unique then a WP_Error 
     1246 * will be passed back. If you don't pass any slug, then a unique one will be created 
     1247 * for you. 
     1248 * 
     1249 * For what can be overrode in $args, check the term scheme can contain and stay away 
     1250 * from the term keys. 
     1251 * 
    12131252 * @package WordPress 
    12141253 * @subpackage Taxonomy 
    12151254 * @since 2.3 
     1255 * 
    12161256 * @uses $wpdb 
     1257 * @uses do_action() Will call both 'edit_term' and 'edit_$taxonomy' twice. 
     1258 * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term id and 
     1259 *      taxonomy id. 
    12171260 * 
    12181261 * @param int $term The ID of the term 
    12191262 * @param string $taxonomy The context in which to relate the term to the object. 
    1220  * @param array|string $args Overwrite defaults 
    1221  * @return array Returns Term ID and Taxonomy Term ID 
     1263 * @param array|string $args Overwrite term field values 
     1264 * @return array|WP_Error Returns Term ID and Taxonomy Term ID 
    12221265 */ 
    12231266function wp_update_term( $term, $taxonomy, $args = array() ) { 
    12241267        global $wpdb; 
     
    13451388// 
    13461389 
    13471390/** 
    1348  * clean_object_term_cache() - {@internal Missing Short Description}} 
     1391 * clean_object_term_cache() - Removes the taxonomy relationship to terms from the cache. 
    13491392 * 
    1350  * {@internal Missing Long Description}} 
     1393 * Will remove the entire taxonomy relationship containing term $object_id. The term IDs 
     1394 * have to exist within the taxonomy $object_type for the deletion to take place. 
    13511395 * 
    13521396 * @package WordPress 
    13531397 * @subpackage Taxonomy 
    13541398 * @since 2.3 
    13551399 * 
    13561400 * @see get_object_taxonomies() for more on $object_type 
     1401 * @uses do_action() Will call action hook named, 'clean_object_term_cache' after completion. 
     1402 *      Passes, function params in same order. 
    13571403 * 
    1358  * @param int|array $object_ids {@internal Missing Description}} 
    1359  * @param string $object_type {@internal Missing Description}} 
     1404 * @param int|array $object_ids Single or list of term object ID(s) 
     1405 * @param string $object_type The taxonomy object type 
    13601406 */ 
    13611407function clean_object_term_cache($object_ids, $object_type) { 
    13621408        if ( !is_array($object_ids) ) 
     
    14171463} 
    14181464 
    14191465/** 
    1420  * get_object_term_cache() - {@internal Missing Short Description}} 
     1466 * get_object_term_cache() - Retrieves the taxonomy relationship to the term object id. 
    14211467 * 
    1422  * {@internal Missing Long Description}} 
    1423  * 
    14241468 * @package WordPress 
    14251469 * @subpackage Taxonomy 
    14261470 * @since 2.3 
    14271471 * 
    1428  * @param int|array $ids {@internal Missing Description}} 
    1429  * @param string $taxonomy {@internal Missing Description}} 
     1472 * @uses wp_cache_get() Retrieves taxonomy relationship from cache 
     1473 * 
     1474 * @param int|array $id Term object ID 
     1475 * @param string $taxonomy Taxonomy Name 
    14301476 * @return bool|array Empty array if $terms found, but not $taxonomy. False if nothing is in cache for $taxonomy and $id. 
    14311477 */ 
    14321478function &get_object_term_cache($id, $taxonomy) { 
     
    14341480} 
    14351481 
    14361482/** 
    1437  * get_object_term_cache() - {@internal Missing Short Description}} 
     1483 * update_object_term_cache() - {@internal Missing Short Description}} 
    14381484 * 
    14391485 * {@internal Missing Long Description}} 
    14401486 * 
     
    15231569/** 
    15241570 * _get_term_hierarchy() - Retrieves children of taxonomy 
    15251571 * 
    1526  * {@internal Missing Long Description}} 
    1527  * 
    15281572 * @package WordPress 
    15291573 * @subpackage Taxonomy 
    15301574 * @access private 
    15311575 * @since 2.3 
    15321576 * 
    1533  * @param string $taxonomy {@internal Missing Description}} 
     1577 * @uses update_option() Stores all of the children in "$taxonomy_children" option. 
     1578 *      That is the name of the taxonomy, immediately followed by '_children'. 
     1579 * 
     1580 * @param string $taxonomy Taxonomy Name 
    15341581 * @return array Empty if $taxonomy isn't hierarachical or returns children. 
    15351582 */ 
    15361583function _get_term_hierarchy($taxonomy) { 
     
    16911738        } 
    16921739} 
    16931740 
    1694 ?> 
     1741?> 
     1742 No newline at end of file