WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Docs: Use third-person singular verbs for function descriptions in `wp-includes/taxonomy.php`, per the documentation standards. 

See #54729.
Built from https://develop.svn.wordpress.org/trunk@52992


git-svn-id: http://core.svn.wordpress.org/trunk@52581 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2022-03-25 16:53:01 +00:00
parent 05dfeab45e
commit 746f1146c9
2 changed files with 59 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
wp-includes/taxonomy.php
View File

@ -247,8 +247,8 @@ function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' )
} }
/** /**
* Return the names or objects of the taxonomies which are registered for the requested object or object type, such as * Returns the names or objects of the taxonomies which are registered for the requested object or object type,
* a post object or post type name. * such as a post object or post type name.
* *
* Example: * Example:
* *
@ -304,7 +304,7 @@ function get_object_taxonomies( $object, $output = 'names' ) {
* @global WP_Taxonomy[] $wp_taxonomies The registered taxonomies. * @global WP_Taxonomy[] $wp_taxonomies The registered taxonomies.
* *
* @param string $taxonomy Name of taxonomy object to return. * @param string $taxonomy Name of taxonomy object to return.
* @return WP_Taxonomy|false The Taxonomy Object or false if $taxonomy doesn't exist. * @return WP_Taxonomy|false The taxonomy object or false if $taxonomy doesn't exist.
*/ */
function get_taxonomy( $taxonomy ) { function get_taxonomy( $taxonomy ) {
global $wp_taxonomies; global $wp_taxonomies;
@ -380,7 +380,7 @@ function is_taxonomy_hierarchical( $taxonomy ) {
* @since 4.4.0 The `public` argument now controls whether the taxonomy can be queried on the front end. * @since 4.4.0 The `public` argument now controls whether the taxonomy can be queried on the front end.
* @since 4.5.0 Introduced `publicly_queryable` argument. * @since 4.5.0 Introduced `publicly_queryable` argument.
* @since 4.7.0 Introduced `show_in_rest`, 'rest_base' and 'rest_controller_class' * @since 4.7.0 Introduced `show_in_rest`, 'rest_base' and 'rest_controller_class'
* arguments to register the Taxonomy in REST API. * arguments to register the taxonomy in REST API.
* @since 5.1.0 Introduced `meta_box_sanitize_cb` argument. * @since 5.1.0 Introduced `meta_box_sanitize_cb` argument.
* @since 5.4.0 Added the registered taxonomy object as a return value. * @since 5.4.0 Added the registered taxonomy object as a return value.
* @since 5.5.0 Introduced `default_term` argument. * @since 5.5.0 Introduced `default_term` argument.
@ -735,7 +735,7 @@ function get_taxonomy_labels( $tax ) {
} }
/** /**
* Add an already registered taxonomy to an object type. * Adds an already registered taxonomy to an object type.
* *
* @since 3.0.0 * @since 3.0.0
* *
@ -777,7 +777,7 @@ function register_taxonomy_for_object_type( $taxonomy, $object_type ) {
} }
/** /**
* Remove an already registered taxonomy from an object type. * Removes an already registered taxonomy from an object type.
* *
* @since 3.7.0 * @since 3.7.0
* *
@ -823,7 +823,7 @@ function unregister_taxonomy_for_object_type( $taxonomy, $object_type ) {
// //
/** /**
* Retrieve object IDs of valid taxonomy and term. * Retrieves object IDs of valid taxonomy and term.
* *
* The strings of `$taxonomies` must exist before this function will continue. * The strings of `$taxonomies` must exist before this function will continue.
* On failure of finding a valid taxonomy, it will return a WP_Error. * On failure of finding a valid taxonomy, it will return a WP_Error.
@ -905,7 +905,7 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
} }
/** /**
* Get all Term data from database by Term ID. * Gets all term data from database by term ID.
* *
* The usage of the get_term function is to apply filters to a term object. It * The usage of the get_term function is to apply filters to a term object. It
* is possible to get a term object from the database before applying the * is possible to get a term object from the database before applying the
@ -918,7 +918,7 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
* There are two hooks, one is specifically for each term, named 'get_term', and * There are two hooks, one is specifically for each term, named 'get_term', and
* the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the * the second is for the taxonomy name, 'term_$taxonomy'. Both hooks gets the
* term object, and the taxonomy name as parameters. Both hooks are expected to * term object, and the taxonomy name as parameters. Both hooks are expected to
* return a Term object. * return a term object.
* *
* {@see 'get_term'} hook - Takes two parameters the term Object and the taxonomy name. * {@see 'get_term'} hook - Takes two parameters the term Object and the taxonomy name.
* Must return term object. Used in get_term() as a catch-all filter for every * Must return term object. Used in get_term() as a catch-all filter for every
@ -1032,7 +1032,7 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
} }
/** /**
* Get all Term data from database by Term field and data. * Gets all term data from database by term field and data.
* *
* Warning: $value is not escaped for 'name' $field. You must do it yourself, if * Warning: $value is not escaped for 'name' $field. You must do it yourself, if
* required. * required.
@ -1041,7 +1041,7 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
* field, but not recommended that you do so. * field, but not recommended that you do so.
* *
* If $value does not exist, the return value will be false. If $taxonomy exists * If $value does not exist, the return value will be false. If $taxonomy exists
* and $field and $value combinations exist, the Term will be returned. * and $field and $value combinations exist, the term will be returned.
* *
* This function will always return the first term that matches the `$field`- * This function will always return the first term that matches the `$field`-
* `$value`-`$taxonomy` combination specified in the parameters. If your query * `$value`-`$taxonomy` combination specified in the parameters. If your query
@ -1133,7 +1133,7 @@ function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter
} }
/** /**
* Merge all term children into a single array of their IDs. * Merges all term children into a single array of their IDs.
* *
* This recursive function will merge all of the children of $term into the same * This recursive function will merge all of the children of $term into the same
* array of term IDs. Only useful for taxonomies which are hierarchical. * array of term IDs. Only useful for taxonomies which are hierarchical.
@ -1144,7 +1144,7 @@ function get_term_by( $field, $value, $taxonomy = '', $output = OBJECT, $filter
* *
* @param int $term_id ID of term to get children. * @param int $term_id ID of term to get children.
* @param string $taxonomy Taxonomy name. * @param string $taxonomy Taxonomy name.
* @return array|WP_Error List of Term IDs. WP_Error returned if `$taxonomy` does not exist. * @return array|WP_Error List of term IDs. WP_Error returned if `$taxonomy` does not exist.
*/ */
function get_term_children( $term_id, $taxonomy ) { function get_term_children( $term_id, $taxonomy ) {
if ( ! taxonomy_exists( $taxonomy ) ) { if ( ! taxonomy_exists( $taxonomy ) ) {
@ -1175,7 +1175,7 @@ function get_term_children( $term_id, $taxonomy ) {
} }
/** /**
* Get sanitized Term field. * Gets sanitized term field.
* *
* The function is for contextual reasons and for simplicity of usage. * The function is for contextual reasons and for simplicity of usage.
* *
@ -1209,7 +1209,7 @@ function get_term_field( $field, $term, $taxonomy = '', $context = 'display' ) {
} }
/** /**
* Sanitizes Term for editing. * Sanitizes term for editing.
* *
* Return value is sanitize_term() and usage is for sanitizing the term for * Return value is sanitize_term() and usage is for sanitizing the term for
* editing. Function is for contextual and simplicity. * editing. Function is for contextual and simplicity.
@ -1456,7 +1456,7 @@ function update_termmeta_cache( $term_ids ) {
} }
/** /**
* Get all meta data, including meta IDs, for the given term ID. * Gets all meta data, including meta IDs, for the given term ID.
* *
* @since 4.9.0 * @since 4.9.0
* *
@ -1614,7 +1614,7 @@ function term_exists( $term, $taxonomy = '', $parent = null ) {
} }
/** /**
* Check if a term is an ancestor of another term. * Checks if a term is an ancestor of another term.
* *
* You can use either an ID or the term object for both parameters. * You can use either an ID or the term object for both parameters.
* *
@ -1644,7 +1644,7 @@ function term_is_ancestor_of( $term1, $term2, $taxonomy ) {
} }
/** /**
* Sanitize all term fields. * Sanitizes all term fields.
* *
* Relies on sanitize_term_field() to sanitize the term. The difference is that * Relies on sanitize_term_field() to sanitize the term. The difference is that
* this function will sanitize **all** fields. The context is based * this function will sanitize **all** fields. The context is based
@ -1690,7 +1690,7 @@ function sanitize_term( $term, $taxonomy, $context = 'display' ) {
} }
/** /**
* Cleanse the field value in the term based on the context. * Sanitizes the field value in the term based on the context.
* *
* Passing a term field value through the function should be assumed to have * 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. * cleansed the value for whatever context the term field is going to be used.
@ -1872,7 +1872,7 @@ function sanitize_term_field( $field, $value, $term_id, $taxonomy, $context ) {
} }
/** /**
* Count how many terms are in Taxonomy. * Counts how many terms are in taxonomy.
* *
* Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true). * Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true).
* *
@ -1922,7 +1922,7 @@ function wp_count_terms( $args = array(), $deprecated = '' ) {
} }
/** /**
* Will unlink the object from the taxonomy or taxonomies. * Unlinks the object from the taxonomy or taxonomies.
* *
* Will remove all relationships between the object and any terms in * Will remove all relationships between the object and any terms in
* a particular taxonomy or taxonomies. Does not remove the term or * a particular taxonomy or taxonomies. Does not remove the term or
@ -2310,7 +2310,7 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
} }
/** /**
* Add a new term to the database. * Adds a new term to the database.
* *
* A non-existent term is inserted in the following sequence: * A non-existent term is inserted in the following sequence:
* 1. The term is added to the term table, then related to the taxonomy. * 1. The term is added to the term table, then related to the taxonomy.
@ -2559,7 +2559,7 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
/** /**
* Filters the duplicate term check that takes place during term creation. * Filters the duplicate term check that takes place during term creation.
* *
* Term parent+taxonomy+slug combinations are meant to be unique, and wp_insert_term() * Term parent + taxonomy + slug combinations are meant to be unique, and wp_insert_term()
* performs a last-minute confirmation of this uniqueness before allowing a new term * performs a last-minute confirmation of this uniqueness before allowing a new term
* to be created. Plugins with different uniqueness requirements may use this filter * to be created. Plugins with different uniqueness requirements may use this filter
* to bypass or modify the duplicate-term check. * to bypass or modify the duplicate-term check.
@ -2705,9 +2705,9 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
} }
/** /**
* Create Term and Taxonomy Relationships. * Creates term and taxonomy relationships.
* *
* Relates an object (post, link etc) to a term and taxonomy type. Creates the * 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 * term and taxonomy relationship if it doesn't already exist. Creates a term if
* it doesn't exist (using the slug). * it doesn't exist (using the slug).
* *
@ -2889,7 +2889,7 @@ function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
} }
/** /**
* Add term(s) associated with a given object. * Adds term(s) associated with a given object.
* *
* @since 3.6.0 * @since 3.6.0
* *
@ -2903,7 +2903,7 @@ function wp_add_object_terms( $object_id, $terms, $taxonomy ) {
} }
/** /**
* Remove term(s) associated with a given object. * Removes term(s) associated with a given object.
* *
* @since 3.6.0 * @since 3.6.0
* *
@ -2990,7 +2990,7 @@ function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
} }
/** /**
* Will make slug unique, if it isn't already. * Makes term slug unique, if it isn't already.
* *
* The `$slug` has to be unique global to every taxonomy, meaning that one * The `$slug` has to be unique global to every taxonomy, meaning that one
* taxonomy term can't have a matching slug with another taxonomy term. Each * taxonomy term can't have a matching slug with another taxonomy term. Each
@ -3093,7 +3093,7 @@ function wp_unique_term_slug( $slug, $term ) {
} }
/** /**
* Update term based on arguments provided. * Updates term based on arguments provided.
* *
* The `$args` will indiscriminately override all values with the same field name. * 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 * Care must be taken to not override important information need to update or
@ -3288,7 +3288,7 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
* *
* @since 2.9.0 * @since 2.9.0
* *
* @param int $term_id Term ID * @param int $term_id Term ID.
* @param string $taxonomy Taxonomy slug. * @param string $taxonomy Taxonomy slug.
*/ */
do_action( 'edited_terms', $term_id, $taxonomy ); do_action( 'edited_terms', $term_id, $taxonomy );
@ -3397,7 +3397,7 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
} }
/** /**
* Enable or disable term counting. * Enables or disables term counting.
* *
* @since 2.5.0 * @since 2.5.0
* *
@ -3464,7 +3464,7 @@ function wp_update_term_count( $terms, $taxonomy, $do_deferred = false ) {
} }
/** /**
* Perform term count update immediately. * Performs term count update immediately.
* *
* @since 2.5.0 * @since 2.5.0
* *
@ -3551,7 +3551,7 @@ function clean_object_term_cache( $object_ids, $object_type ) {
} }
/** /**
* Will remove all of the term IDs from the cache. * Removes all of the term IDs from the cache.
* *
* @since 2.3.0 * @since 2.3.0
* *
@ -3616,7 +3616,7 @@ function clean_term_cache( $ids, $taxonomy = '', $clean_taxonomy = true ) {
} }
/** /**
* Clean the caches for a taxonomy. * Cleans the caches for a taxonomy.
* *
* @since 4.9.0 * @since 4.9.0
* *
@ -3777,7 +3777,7 @@ function update_object_term_cache( $object_ids, $object_type ) {
} }
/** /**
* Updates Terms to Taxonomy in cache. * Updates terms in cache.
* *
* @since 2.3.0 * @since 2.3.0
* *
@ -3803,13 +3803,13 @@ function update_term_cache( $terms, $taxonomy = '' ) {
// //
/** /**
* Retrieves children of taxonomy as Term IDs. * Retrieves children of taxonomy as term IDs.
* *
* @access private * @access private
* @since 2.3.0 * @since 2.3.0
* *
* @param string $taxonomy Taxonomy name. * @param string $taxonomy Taxonomy name.
* @return array Empty if $taxonomy isn't hierarchical or returns children as Term IDs. * @return array Empty if $taxonomy isn't hierarchical or returns children as term IDs.
*/ */
function _get_term_hierarchy( $taxonomy ) { function _get_term_hierarchy( $taxonomy ) {
if ( ! is_taxonomy_hierarchical( $taxonomy ) ) { if ( ! is_taxonomy_hierarchical( $taxonomy ) ) {
@ -3841,7 +3841,7 @@ function _get_term_hierarchy( $taxonomy ) {
} }
/** /**
* Get the subset of $terms that are descendants of $term_id. * Gets the subset of $terms that are descendants of $term_id.
* *
* If `$terms` is an array of objects, then _get_term_children() returns an array of objects. * If `$terms` is an array of objects, then _get_term_children() returns an array of objects.
* If `$terms` is an array of IDs, then _get_term_children() returns an array of IDs. * If `$terms` is an array of IDs, then _get_term_children() returns an array of IDs.
@ -3917,7 +3917,7 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
} }
/** /**
* Add count of children to parent count. * Adds count of children to parent count.
* *
* Recalculates term counts by including items from child terms. Assumes all * Recalculates term counts by including items from child terms. Assumes all
* relevant children are already in the $terms argument. * relevant children are already in the $terms argument.
@ -4024,7 +4024,7 @@ function _prime_term_caches( $term_ids, $update_meta_cache = true ) {
// //
/** /**
* Will update term count based on object types of the current taxonomy. * Updates term count based on object types of the current taxonomy.
* *
* Private function for the default callback for post_tag and category * Private function for the default callback for post_tag and category
* taxonomies. * taxonomies.
@ -4034,7 +4034,7 @@ function _prime_term_caches( $term_ids, $update_meta_cache = true ) {
* *
* @global wpdb $wpdb WordPress database abstraction object. * @global wpdb $wpdb WordPress database abstraction object.
* *
* @param int[] $terms List of Term taxonomy IDs. * @param int[] $terms List of term taxonomy IDs.
* @param WP_Taxonomy $taxonomy Current taxonomy object of terms. * @param WP_Taxonomy $taxonomy Current taxonomy object of terms.
*/ */
function _update_post_term_count( $terms, $taxonomy ) { function _update_post_term_count( $terms, $taxonomy ) {
@ -4094,7 +4094,7 @@ function _update_post_term_count( $terms, $taxonomy ) {
} }
/** /**
* Will update term count based on number of objects. * Updates term count based on number of objects.
* *
* Default callback for the 'link_category' taxonomy. * Default callback for the 'link_category' taxonomy.
* *
@ -4121,7 +4121,7 @@ function _update_generic_term_count( $terms, $taxonomy ) {
} }
/** /**
* Create a new term for a term_taxonomy item that currently shares its term * Creates a new term for a term_taxonomy item that currently shares its term
* with another term_taxonomy. * with another term_taxonomy.
* *
* @ignore * @ignore
@ -4368,7 +4368,7 @@ function _wp_batch_split_terms() {
/** /**
* In order to avoid the _wp_batch_split_terms() job being accidentally removed, * In order to avoid the _wp_batch_split_terms() job being accidentally removed,
* check that it's still scheduled while we haven't finished splitting terms. * checks that it's still scheduled while we haven't finished splitting terms.
* *
* @ignore * @ignore
* @since 4.3.0 * @since 4.3.0
@ -4380,7 +4380,7 @@ function _wp_check_for_scheduled_split_terms() {
} }
/** /**
* Check default categories when a term gets split to see if any of them need to be updated. * Checks default categories when a term gets split to see if any of them need to be updated.
* *
* @ignore * @ignore
* @since 4.2.0 * @since 4.2.0
@ -4403,7 +4403,7 @@ function _wp_check_split_default_terms( $term_id, $new_term_id, $term_taxonomy_i
} }
/** /**
* Check menu items when a term gets split to see if any of them need to be updated. * Checks menu items when a term gets split to see if any of them need to be updated.
* *
* @ignore * @ignore
* @since 4.2.0 * @since 4.2.0
@ -4439,7 +4439,7 @@ function _wp_check_split_terms_in_menus( $term_id, $new_term_id, $term_taxonomy_
} }
/** /**
* If the term being split is a nav_menu, change associations. * If the term being split is a nav_menu, changes associations.
* *
* @ignore * @ignore
* @since 4.3.0 * @since 4.3.0
@ -4465,7 +4465,7 @@ function _wp_check_split_nav_menu_terms( $term_id, $new_term_id, $term_taxonomy_
} }
/** /**
* Get data about terms that previously shared a single term_id, but have since been split. * Gets data about terms that previously shared a single term_id, but have since been split.
* *
* @since 4.2.0 * @since 4.2.0
* *
@ -4484,7 +4484,7 @@ function wp_get_split_terms( $old_term_id ) {
} }
/** /**
* Get the new term ID corresponding to a previously split term. * Gets the new term ID corresponding to a previously split term.
* *
* @since 4.2.0 * @since 4.2.0
* *
@ -4506,7 +4506,7 @@ function wp_get_split_term( $old_term_id, $taxonomy ) {
} }
/** /**
* Determine whether a term is shared between multiple taxonomies. * Determines whether a term is shared between multiple taxonomies.
* *
* Shared taxonomy terms began to be split in 4.3, but failed cron tasks or * Shared taxonomy terms began to be split in 4.3, but failed cron tasks or
* other delays in upgrade routines may cause shared terms to remain. * other delays in upgrade routines may cause shared terms to remain.
@ -4530,7 +4530,7 @@ function wp_term_is_shared( $term_id ) {
} }
/** /**
* Generate a permalink for a taxonomy term archive. * Generates a permalink for a taxonomy term archive.
* *
* @since 2.5.0 * @since 2.5.0
* *
@ -4644,7 +4644,7 @@ function get_term_link( $term, $taxonomy = '' ) {
} }
/** /**
* Display the taxonomies of a post with available options. * Displays the taxonomies of a post with available options.
* *
* This function can be used within the loop to display the taxonomies for a * This function can be used within the loop to display the taxonomies for a
* post without specifying the Post ID. You can also use it outside the Loop to * post without specifying the Post ID. You can also use it outside the Loop to
@ -4676,7 +4676,7 @@ function the_taxonomies( $args = array() ) {
} }
/** /**
* Retrieve all taxonomies associated with a post. * Retrieves all taxonomies associated with a post.
* *
* This function can be used within the loop. It will also return an array of * This function can be used within the loop. It will also return an array of
* the taxonomies with links to the taxonomy and name. * the taxonomies with links to the taxonomy and name.
@ -4744,7 +4744,7 @@ function get_the_taxonomies( $post = 0, $args = array() ) {
} }
/** /**
* Retrieve all taxonomy names for the given post. * Retrieves all taxonomy names for the given post.
* *
* @since 2.5.0 * @since 2.5.0
* *
@ -4758,7 +4758,7 @@ function get_post_taxonomies( $post = 0 ) {
} }
/** /**
* Determine if the given object is associated with any of the given terms. * Determines if the given object is associated with any of the given terms.
* *
* The given terms are checked against the object's terms' term_ids, names and slugs. * The given terms are checked against the object's terms' term_ids, names and slugs.
* Terms given as integers will only be checked against the object's terms' term_ids. * Terms given as integers will only be checked against the object's terms' term_ids.
@ -4833,7 +4833,7 @@ function is_object_in_term( $object_id, $taxonomy, $terms = null ) {
} }
/** /**
* Determine if the given object type is associated with the given taxonomy. * Determines if the given object type is associated with the given taxonomy.
* *
* @since 3.0.0 * @since 3.0.0
* *
@ -4850,7 +4850,7 @@ function is_object_in_taxonomy( $object_type, $taxonomy ) {
} }
/** /**
* Get an array of ancestor IDs for a given object. * Gets an array of ancestor IDs for a given object.
* *
* @since 3.1.0 * @since 3.1.0
* @since 4.1.0 Introduced the `$resource_type` argument. * @since 4.1.0 Introduced the `$resource_type` argument.
@ -4906,7 +4906,7 @@ function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' )
} }
/** /**
* Returns the term's parent's term_ID. * Returns the term's parent's term ID.
* *
* @since 3.1.0 * @since 3.1.0
* *

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
* *
* @global string $wp_version * @global string $wp_version
*/ */
$wp_version = '6.0-alpha-52991'; $wp_version = '6.0-alpha-52992';
/** /**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.