Ticket #4742: taxonomy.r6291.phpdoc.patch

taxonomy.php

@@ -235 +235 @@
  * name as parameters. Both hooks are expected to return a Term object.
  *
  * 'get_term' hook - Takes two parameters the term Object and the taxonomy name. Must return
- * term object. Used in @see get_term() as a catch-all filter for every $term.
+ * term object. Used in get_term() as a catch-all filter for every $term.
  *
  * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy name. Must return
  * term object. $taxonomy will be the taxonomy name, so for example, if 'category', it would be
@@ -246 +246 @@
  * @since 2.3
  *
  * @uses $wpdb
+ * @uses sanitize_term() Cleanses the term based on $filter context before returning.
+ * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
  *
  * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
  * @param string $taxonomy Taxonomy name that $term is part of.
  * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
- * @param string $filter {@internal Missing Description}}
+ * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
  * @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
  * exist then WP_Error will be returned.
  */
@@ -305 +307 @@
  * @since 2.3
  *
  * @uses $wpdb
+ * @uses sanitize_term() Cleanses the term based on $filter context before returning.
+ * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
  *
  * @param string $field Either 'slug', 'name', or 'id'
  * @param string|int $value Search for this term value
  * @param string $taxonomy Taxonomy Name
  * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
- * @param string $filter {@internal Missing Description}}
+ * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
  * @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found.
  */
 function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') {
@@ -394 +398 @@
  * get_term_field() - Get sanitized Term field
  * 
  * Does checks for $term, based on the $taxonomy. The function is for
- * contextual reasons and for simplicity of usage. @see sanitize_term_field() for
+ * contextual reasons and for simplicity of usage. See sanitize_term_field() for
  * more information.
  *
  * @package WordPress
@@ -406 +410 @@
  * @param string $field Term field to fetch
  * @param int $term Term ID
  * @param string $taxonomy Taxonomy Name
- * @param string $context {@internal Missing Description}}
+ * @param string $context Optional, default is display. Look at sanitize_term_field() for available options.
  * @return mixed Will return an empty string if $term is not an object or if $field is not set in $term.
  */
 function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
@@ -427 +431 @@
 /**
  * get_term_to_edit() - Sanitizes Term for editing
  *
- * Return value is @see sanitize_term() and usage is for sanitizing the term
+ * Return value is sanitize_term() and usage is for sanitizing the term
  * for editing. Function is for contextual and simplicity.
  * 
  * @package WordPress
@@ -713 +717 @@
 /**
  * sanitize_term() - Sanitize Term all fields
  *
- * Relys on @see sanitize_term_field() to sanitize the term. The difference
+ * Relys on sanitize_term_field() to sanitize the term. The difference
  * is that this function will sanitize <strong>all</strong> fields. The context
- * is based on @see sanitize_term_field().
+ * is based on sanitize_term_field().
  *
  * The $term is expected to be either an array or an object.
  *
@@ -748 +752 @@
 }
 
 /**
- * sanitize_term_field() - {@internal Missing Short Description}}
+ * sanitize_term_field() - Cleanse the field value in the term based on the context
  *
- * {@internal Missing Long Description}}
+ * Passing a term field value through the function should be assumed to have cleansed
+ * the value for whatever context the term field is going to be used.
  *
+ * If no context or an unsupported context is given, then default filters will be applied.
+ *
+ * There are enough filters for each context to support a custom filtering without creating
+ * your own filter function. Simply create a function that hooks into the filter you need.
+ *
  * @package WordPress
  * @subpackage Taxonomy
  * @since 2.3
@@ -834 +844 @@
 }
 
 /**
- * wp_delete_object_term_relationships() - {@internal Missing Short Description}}
+ * wp_delete_object_term_relationships() - Will unlink the term from the taxonomy
  *
- * {@internal Missing Long Description}}
+ * Will remove the term's relationship to the taxonomy, not the term or taxonomy itself.
+ * The term and taxonomy will still exist. Will require the term's object ID to perform
+ * the operation.
  *
  * @package WordPress
  * @subpackage Taxonomy
@@ -865 +877 @@
 /**
  * wp_delete_term() - Removes a term from the database.
  *
- * {@internal Missing Long Description}}
+ * If the term is a parent of other terms, then the children will be updated
+ * to that term's parent.
  *
+ * The $args 'default' will only override the terms found, if there is only one
+ * term found. Any other and the found terms are used.
+ *
  * @package WordPress
  * @subpackage Taxonomy
  * @since 2.3
+ *
  * @uses $wpdb
+ * @uses do_action() Calls both 'delete_term' and 'delete_$taxonomy' action hooks,
+ *      passing term object, term id. 'delete_term' gets an additional parameter with
+ *      the $taxonomy parameter.
  *
  * @param int $term Term ID
  * @param string $taxonomy Taxonomy Name
- * @param array|string $args Change Default
- * @return bool Returns false if not term; true if completes delete action.
+ * @param array|string $args Optional. Change 'default' term id and override found term ids.
+ * @return bool|WP_Error Returns false if not term; true if completes delete action.
  */
 function wp_delete_term( $term, $taxonomy, $args = array() ) {
         global $wpdb;
@@ -933 +953 @@
 }
 
 /**
- * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies.
+ * wp_get_object_terms() - Retrieves the terms associated with the given object(s), in the supplied taxonomies.
  *
  * {@internal Missing Long Description}}
  *
@@ -942 +962 @@
  * @since 2.3
  * @uses $wpdb
  *
- * @param int|array $object_id The id of the object(s)) to retrieve.
+ * @param int|array $object_id The id of the object(s) to retrieve.
  * @param string|array $taxonomies The taxonomies to retrieve terms from.
  * @param array|string $args Change what is returned
  * @return array|WP_Error The requested term data or empty array if no terms found. WP_Error if $taxonomy does not exist.
@@ -1088 +1108 @@
 }
 
 /**
- * wp_set_object_terms() - {@internal Missing Short Description}}
+ * wp_set_object_terms() - Create Term and Taxonomy Relationships
  * 
- * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy
- * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug).
+ * Relates an object (post, link etc) to a term and taxonomy type. Creates the term and taxonomy
+ * relationship if it doesn't already exist. Creates a term if it doesn't exist (using the slug).
  *
+ * A relationship means that the term is grouped in or belongs to the taxonomy. A term has no
+ * meaning until it is given context by defining which taxonomy it exists under.
+ *
  * @package WordPress
  * @subpackage Taxonomy
  * @since 2.3
@@ -1206 +1229 @@
 }
 
 /**
- * wp_update_term() - {@internal Missing Short Description}}
+ * wp_update_term() - Update term based on arguments provided
  *
- * {@internal Missing Long Description}}
+ * The $args will indiscriminately override all values with the same field name. Care
+ * must be taken to not override important information need to update or update will
+ * fail (or perhaps create a new term, neither would be acceptable).
  *
+ * Defaults will set 'alias_of', 'description', 'parent', and 'slug' if not defined
+ * in $args already.
+ *
+ * 'alias_of' will create a term group, if it doesn't already exist, and update it for
+ * the $term.
+ *
+ * If the 'slug' argument in $args is missing, then the 'name' in $args will be used.
+ * It should also be noted that if you set 'slug' and it isn't unique then a WP_Error
+ * will be passed back. If you don't pass any slug, then a unique one will be created
+ * for you.
+ *
+ * For what can be overrode in $args, check the term scheme can contain and stay away
+ * from the term keys.
+ *
  * @package WordPress
  * @subpackage Taxonomy
  * @since 2.3
+ *
  * @uses $wpdb
+ * @uses do_action() Will call both 'edit_term' and 'edit_$taxonomy' twice.
+ * @uses apply_filters() Will call the 'term_id_filter' filter and pass the term id and
+ *      taxonomy id.
  *
  * @param int $term The ID of the term
  * @param string $taxonomy The context in which to relate the term to the object.
- * @param array|string $args Overwrite defaults
- * @return array Returns Term ID and Taxonomy Term ID
+ * @param array|string $args Overwrite term field values
+ * @return array|WP_Error Returns Term ID and Taxonomy Term ID
  */
 function wp_update_term( $term, $taxonomy, $args = array() ) {
         global $wpdb;
@@ -1345 +1388 @@
 //
 
 /**
- * clean_object_term_cache() - {@internal Missing Short Description}}
+ * clean_object_term_cache() - Removes the taxonomy relationship to terms from the cache.
  *
- * {@internal Missing Long Description}}
+ * Will remove the entire taxonomy relationship containing term $object_id. The term IDs
+ * have to exist within the taxonomy $object_type for the deletion to take place.
  *
  * @package WordPress
  * @subpackage Taxonomy
  * @since 2.3
  *
  * @see get_object_taxonomies() for more on $object_type
+ * @uses do_action() Will call action hook named, 'clean_object_term_cache' after completion.
+ *      Passes, function params in same order.
  *
- * @param int|array $object_ids {@internal Missing Description}}
- * @param string $object_type {@internal Missing Description}}
+ * @param int|array $object_ids Single or list of term object ID(s)
+ * @param string $object_type The taxonomy object type
  */
 function clean_object_term_cache($object_ids, $object_type) {
         if ( !is_array($object_ids) )
@@ -1417 +1463 @@
 }
 
 /**
- * get_object_term_cache() - {@internal Missing Short Description}}
+ * get_object_term_cache() - Retrieves the taxonomy relationship to the term object id.
  *
- * {@internal Missing Long Description}}
- *
  * @package WordPress
  * @subpackage Taxonomy
  * @since 2.3
  *
- * @param int|array $ids {@internal Missing Description}}
- * @param string $taxonomy {@internal Missing Description}}
+ * @uses wp_cache_get() Retrieves taxonomy relationship from cache
+ *
+ * @param int|array $id Term object ID
+ * @param string $taxonomy Taxonomy Name
  * @return bool|array Empty array if $terms found, but not $taxonomy. False if nothing is in cache for $taxonomy and $id.
  */
 function &get_object_term_cache($id, $taxonomy) {
@@ -1434 +1480 @@
 }
 
 /**
- * get_object_term_cache() - {@internal Missing Short Description}}
+ * update_object_term_cache() - {@internal Missing Short Description}}
  *
  * {@internal Missing Long Description}}
  *
@@ -1523 +1569 @@
 /**
  * _get_term_hierarchy() - Retrieves children of taxonomy
  *
- * {@internal Missing Long Description}}
- *
  * @package WordPress
  * @subpackage Taxonomy
  * @access private
  * @since 2.3
  *
- * @param string $taxonomy {@internal Missing Description}}
+ * @uses update_option() Stores all of the children in "$taxonomy_children" option.
+ *      That is the name of the taxonomy, immediately followed by '_children'.
+ *
+ * @param string $taxonomy Taxonomy Name
  * @return array Empty if $taxonomy isn't hierarachical or returns children.
  */
 function _get_term_hierarchy($taxonomy) {
@@ -1691 +1738 @@
         }
 }
 
-?>
+?>
+ No newline at end of file