WordPress.org

Make WordPress Core

Ticket #4742: taxonomy.phpdoc.r5900.diff

File taxonomy.phpdoc.r5900.diff, 16.7 KB (added by darkdragon, 11 years ago)

Completed more phpDoc for functions. Fixed some previous descriptions, and added blank descriptions with params and return completed to other functions.

  • taxonomy.php

     
    1313$wp_taxonomies['link_category'] = (object) array('name' => 'link_category', 'object_type' => 'link', 'hierarchical' => false);
    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
    1919 * $wp_taxonomies global variable.
     
    3131 * @return array The names of all within the object_type.
    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) {
    3837        global $wp_taxonomies;
     
    5554 * @package Taxonomy
    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 ) {
    6563        global $wp_taxonomies;
     
    7977 * @return bool Whether the taxonomy exists or not.
    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 ) {
    8683        global $wp_taxonomies;
     
    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.
    9693 *
     94 * A false return value, might also mean that the taxonomy does not exist.
     95 *
    9796 * @package Taxonomy
    9897 * @global array $wp_taxonomies
    9998 * @param string $taxonomy Name of taxonomy object
    10099 * @return bool Whether the taxonomy is hierarchical
    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) {
    107105        if ( ! is_taxonomy($taxonomy) )
     
    122120 * functions to still work. It is possible to overwrite the default set, which contains two
    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
    128126 *      somewhere).
     
    131129 * @global array $wp_taxonomies
    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() ) {
    142139        global $wp_taxonomies;
     
    172169 * @global object $wpdb Database Query
    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
    178175 * @return array Array of $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() ) {
    185181        global $wpdb;
     
    213209}
    214210
    215211/**
    216  * get_term() -
     212 * get_term() - Get all Term data from database by Term ID.
    217213 *
    218  *
     214 * The usage of the get_term function is to apply filters to a term object.
     215 * It is possible to get a term object from the database before applying the
     216 * filters.
    219217 *
     218 * $term ID must be part of $taxonomy, to get from the database. Failure, might be
     219 * able to be captured by the hooks. Failure would be the same value as $wpdb returns for the
     220 * get_row method.
     221 *
     222 * There are two hooks, one is specifically for each term, named 'get_term', and the second is
     223 * for the taxonomy name. Both hooks gets the term object, and the taxonomy name as parameters.
     224 * Both hooks are expected to return a Term object.
     225 *
    220226 * @package Taxonomy
    221227 * @subpackage Term
    222228 * @global object $wpdb Database Query
    223  * @param int|object $term
    224  * @param string $taxonomy
    225  * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N
     229 * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
     230 * @param string $taxonomy Taxonomy name that $term is part of.
     231 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
    226232 * @return mixed Term Row from database
    227233 *
    228234 * @internal
    229  *      This won't appear but just a note to say that this is all conjecture and parts or whole
    230  *      might be inaccurate or wrong.
     235 *   This is all conjecture and might be partially or completely inaccurate.
     236 *
     237 *   The @filter and @action phpDoc tags is not supported by phpDoc software. It is for custom phpDoc plugin or custom
     238 *   solution for getting the tag. I would choose to write a custom phpDoc plugin than custom solution.
    231239 */
    232240function &get_term(&$term, $taxonomy, $output = OBJECT) {
    233241        global $wpdb;
     
    248256                        wp_cache_add($term, $_term, $taxonomy);
    249257                }
    250258        }
    251 
     259       
     260        /**
     261         * @internal
     262         * Filter tag is basically: filter 'type' 'hook_name' 'description'
     263         *
     264         * Takes two parameters the term Object and the taxonomy name. Must return term object.
     265         * @filter object get_term Used in @see get_term() as a catch-all filter for every $term
     266         */
    252267        $_term = apply_filters('get_term', $_term, $taxonomy);
     268        /**
     269         * @internal
     270         * Filter tag is basically: filter 'type' 'hook_name' 'description'
     271         *
     272         * Takes two parameters the term Object and the taxonomy name. Must return term object.
     273         * $taxonomy will be the taxonomy name, so for example, if 'category', it would be 'get_category'
     274         * as the filter name.
     275         * Useful for custom taxonomies or plugging into default taxonomies.
     276         * @filter object get_$taxonomy Used in @see get_term() as specific filter for each $taxonomy.
     277         */
    253278        $_term = apply_filters("get_$taxonomy", $_term, $taxonomy);
    254279
    255280        if ( $output == OBJECT ) {
     
    264289}
    265290
    266291/**
    267  * get_term_by() -
     292 * get_term_by() - Get all Term data from database by Term field and data.
    268293 *
     294 * Warning: $value is not escaped for 'name' $field. You must do it yourself, if required.
     295 *
     296 * The default $field is 'id', therefore it is possible to also use null for field, but not
     297 * recommended that you do so.
     298 *
     299 * If $value does not exist, the return value will be false. If $taxonomy exists and $field
     300 * and $value combinations exist, the Term will be returned.
    269301 *
    270  *
    271302 * @package Taxonomy
    272303 * @subpackage Term
    273304 * @global object $wpdb Database Query
    274  * @param string $field
    275  * @param string $value
    276  * @param string $taxonomy
    277  * @param string $output Either OBJECT, ARRAY_A, or ARRAY_N
     305 * @param string $field Either 'slug', 'name', or 'id'
     306 * @param string $value Search for this term value
     307 * @param string $taxonomy Taxonomy Name
     308 * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
    278309 * @return mixed Term Row from database
    279310 *
    280311 * @internal
    281  *      This won't appear but just a note to say that this is all conjecture and parts or whole
    282  *      might be inaccurate or wrong.
     312 *      This is all conjecture and might be partially or completely inaccurate.
    283313 */
    284314function get_term_by($field, $value, $taxonomy, $output = OBJECT) {
    285315        global $wpdb;
     
    317347        }
    318348}
    319349
     350/**
     351 * get_term_children() - Merge all term children into a single array.
     352 *
     353 * This recursive function will merge all of the children of $term into
     354 * the same array.
     355 *
     356 * Only useful for taxonomies which are hierarchical.
     357 *
     358 * @package Taxonomy
     359 * @subpackage Term
     360 * @global object $wpdb Database Query
     361 * @param string $term Name of Term to get children
     362 * @param string $taxonomy Taxonomy Name
     363 * @return array List of Term Objects
     364 *
     365 * @internal
     366 *      This is all conjecture and might be partially or completely inaccurate.
     367 */
    320368function get_term_children( $term, $taxonomy ) {
    321369        if ( ! is_taxonomy($taxonomy) )
    322370                return new WP_Error('invalid_taxonomy', __('Invalid Taxonomy'));
     
    336384        return $children;
    337385}
    338386
     387/**
     388 * get_term_field() - Get sanitized Term field
     389 *
     390 * Does checks for $term, based on the $taxonomy. The function is for
     391 * contextual reasons and for simplicity of usage. @see sanitize_term_field() for
     392 * more information.
     393 *
     394 * @package Taxonomy
     395 * @subpackage Term
     396 * @param string $field Term field to fetch
     397 * @param int $term Term ID
     398 * @param string $taxonomy Taxonomy Name
     399 * @param string $context ??
     400 * @return mixed @see sanitize_term_field()
     401 *
     402 * @internal
     403 *      This is all conjecture and might be partially or completely inaccurate.
     404 */
    339405function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
    340406        $term = (int) $term;
    341407        $term = get_term( $term, $taxonomy );
     
    352418        return sanitize_term_field($field, $term->$field, $term->term_id, $taxonomy, $context);
    353419}
    354420
     421/**
     422 * get_term_to_edit() - Sanitizes Term for editing
     423 *
     424 * Return value is @see sanitize_term() and usage is for sanitizing the term
     425 * for editing. Function is for contextual and simplicity.
     426 *
     427 * @package Taxonomy
     428 * @subpackage Term
     429 * @param int|object $id Term ID or Object
     430 * @param string $taxonomy Taxonomy Name
     431 * @return mixed @see sanitize_term()
     432 *
     433 * @internal
     434 *      This is all conjecture and might be partially or completely inaccurate.
     435 */
    355436function get_term_to_edit( $id, $taxonomy ) {
    356437        $term = get_term( $id, $taxonomy );
    357438
     
    364445        return sanitize_term($term, $taxonomy, 'edit');
    365446}
    366447
     448/**
     449 * get_terms() -
     450 *
     451 *
     452 *
     453 * @package Taxonomy
     454 * @subpackage Term
     455 * @param string|array Taxonomy name or list of Taxonomy names
     456 * @param string|array $args ??
     457 * @return array List of Term Objects and their children.
     458 *
     459 * @internal
     460 *      This is all conjecture and might be partially or completely inaccurate.
     461 */
    367462function &get_terms($taxonomies, $args = '') {
    368463        global $wpdb;
    369464
     
    535630}
    536631
    537632/**
     633 * is_term() - Check if Term exists
     634 *
    538635 * Returns the index of a defined term, or 0 (false) if the term doesn't exist.
     636 *
     637 * @global $wpdb Database Object
     638 * @param int|string $term The term to check
     639 * @param string $taxonomy The taxonomy name to use
     640 * @return mixed Get the term id or Term Object, if exists.
    539641 */
    540642function is_term($term, $taxonomy = '') {
    541643        global $wpdb;
     
    558660        return $wpdb->get_row("SELECT tt.term_id, tt.term_taxonomy_id FROM $wpdb->terms AS t INNER JOIN $wpdb->term_taxonomy as tt ON tt.term_id = t.term_id WHERE $where AND tt.taxonomy = '$taxonomy'", ARRAY_A);
    559661}
    560662
     663/**
     664 * sanitize_term() - Sanitize Term all fields
     665 *
     666 * Relys on @see sanitize_term_field() to sanitize the term. The difference
     667 * is that this function will sanitize <strong>all</strong> fields. The context
     668 * is based on @see sanitize_term_field().
     669 *
     670 * The $term is expected to be either an array or an object.
     671 *
     672 * @param array|object $term The term to check
     673 * @param string $taxonomy The taxonomy name to use
     674 * @param string $context Default is display
     675 * @return array|object Term with all fields sanitized
     676 */
    561677function sanitize_term($term, $taxonomy, $context = 'display') {
    562678        $fields = array('term_id', 'name', 'description', 'slug', 'count', 'term_group');
    563679
     
    575691        return $term;
    576692}
    577693
     694/**
     695 * sanitize_term_field() -
     696 *
     697 *
     698 *
     699 * @global object $wpdb Database Object
     700 * @param string $field Term field to sanitize
     701 * @param string $value Search for this term value
     702 * @param int $term_id Term ID
     703 * @param string $taxonomy Taxonomy Name
     704 * @param string $context Either edit, db, display, attribute, or js.
     705 * @return mixed sanitized field
     706 */
    578707function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
    579708        if ( 'parent' == $field  || 'term_id' == $field || 'count' == $field
    580709                || 'term_group' == $field )
     
    604733        return $value;
    605734}
    606735
     736/**
     737 * wp_count_terms() - Count how many terms are in Taxonomy
     738 *
     739 * Default $args is 'ignore_empty' which can be @example 'ignore_empty=true' or
     740 * @example array('ignore_empty' => true); See @see wp_parse_args() for more
     741 * information on parsing $args.
     742 *
     743 * @global object $wpdb Database Object
     744 * @param string $taxonomy Taxonomy name
     745 * @param array|string $args Overwrite defaults
     746 * @return int How many terms are in $taxonomy
     747 */
    607748function wp_count_terms( $taxonomy, $args = array() ) {
    608749        global $wpdb;
    609750
     
    618759        return $wpdb->get_var("SELECT COUNT(*) FROM $wpdb->term_taxonomy WHERE taxonomy = '$taxonomy' $where");
    619760}
    620761
     762/**
     763 * wp_delete_object_term_relationships() -
     764 *
     765 *
     766 *
     767 * @global object $wpdb Database Object
     768 * @param int $object_id ??
     769 * @param string|array $taxonomy List of Taxonomy Names or single Taxonomy name.
     770 */
    621771function wp_delete_object_term_relationships( $object_id, $taxonomies ) {
    622772        global $wpdb;
    623773
     
    633783                wp_update_term_count($terms, $taxonomy);
    634784        }
    635785
    636         // TODO clear the cache
     786        /** @TODO clear the cache */
    637787}
    638788
    639789/**
    640  * Removes a term from the database.
     790 * wp_delete_term() - Removes a term from the database.
     791 *
     792 *
     793 *
     794 * @global object $wpdb Database Object
     795 * @param int $term Term ID
     796 * @param string $taxonomy Taxonomy Name
     797 * @param array|string $args Change Default
     798 * @param bool Returns false if not term; true if completes delete action.
    641799 */
    642800function wp_delete_term( $term, $taxonomy, $args = array() ) {
    643801        global $wpdb;
     
    691849}
    692850
    693851/**
    694  * Returns the terms associated with the given object(s), in the supplied taxonomies.
     852 * wp_get_object_terms() - Returns the terms associated with the given object(s), in the supplied taxonomies.
     853 *
     854 *
     855 *
     856 * @global $wpdb Database Object
    695857 * @param int|array $object_id The id of the object(s)) to retrieve for.
    696858 * @param string|array $taxonomies The taxonomies to retrieve terms from.
     859 * @param array|string $args Change what is returned
    697860 * @return array The requested term data.                       
    698861 */
    699862function wp_get_object_terms($object_ids, $taxonomies, $args = array()) {
     
    748911}
    749912
    750913/**
    751  * Adds a new term to the database.  Optionally marks it as an alias of an existing term.
     914 * wp_insert_term() - Adds a new term to the database. Optionally marks it as an alias of an existing term.
     915 *
     916 *
     917 *
     918 * @global $wpdb Database Object
    752919 * @param int|string $term The term to add or update.
    753920 * @param string $taxonomy The taxonomy to which to add the term
    754  * @param int|string $alias_of The id or slug of the new term's alias.
     921 * @param array|string $args Change the values of the inserted term
     922 * @return array The Term ID and Term Taxonomy ID
    755923 */
    756924function wp_insert_term( $term, $taxonomy, $args = array() ) {
    757925        global $wpdb;
     
    818986}
    819987
    820988/**
     989 * wp_set_object_terms() -
     990 *
    821991 * Relates an object (post, link etc) to a term and taxonomy type.  Creates the term and taxonomy
    822992 * relationship if it doesn't already exist.  Creates a term if it doesn't exist (using the slug).
     993 *
     994 * @global $wpdb Database Object
    823995 * @param int $object_id The object to relate to.
    824996 * @param array|int|string $term The slug or id of the term.
    825997 * @param array|string $taxonomy The context in which to relate the term to the object.
     998 * @param bool $append If false will delete difference of terms.
    826999 */
    8271000function wp_set_object_terms($object_id, $terms, $taxonomy, $append = false) {
    8281001        global $wpdb;
     
    11201293        }
    11211294}
    11221295
    1123 ?>
    1124  No newline at end of file
     1296?>