WordPress.org

Make WordPress Core

Changeset 6092


Ignore:
Timestamp:
09/12/2007 02:56:44 AM (11 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.