Improve inline documentation in wp-includes/taxonomy.php.

* Adds missing `@since` versions
* Adds `@global` tags and descriptions to DocBlocks where appropriate

Props ChaseWiseman.
See #31800.


git-svn-id: https://develop.svn.wordpress.org/trunk@32348 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/taxonomy.php

@@ -2,9 +2,10 @@
 /**
  * Taxonomy API
  *
+ * @since 2.3.0
+ *
  * @package WordPress
  * @subpackage Taxonomy
- * @since 2.3.0
  */
 
 //
@@ -15,8 +16,12 @@
  * Creates the initial taxonomies.
  *
  * This function fires twice: in wp-settings.php before plugins are loaded (for
- * backwards compatibility reasons), and again on the 'init' action. We must avoid
+ * backwards compatibility reasons), and again on the {@see 'init'} action. We must
- * registering rewrite rules before the 'init' action.
+ * avoid registering rewrite rules before the {@see 'init'} action.
+ *
+ * @since 2.8.0
+ *
+ * @global WP_Rewrite $wp_rewrite The WordPress rewrite class.
  */
 function create_initial_taxonomies() {
 	global $wp_rewrite;
@@ -129,10 +134,11 @@ function create_initial_taxonomies() {
 }
 
 /**
- * Get a list of registered taxonomy objects.
+ * Retrieves a list of registered taxonomy names or objects.
  *
  * @since 3.0.0
- * @uses $wp_taxonomies
+ *
+ * @global array $wp_taxonomies The registered taxonomies.
  *
  * @param array $args An array of key => value arguments to match against the taxonomy objects.
  * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
@@ -159,7 +165,7 @@ function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' )
  *
  * @since 2.3.0
  *
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
  *
  * @param array|string|object $object Name of the type of taxonomy object, or an object (row from posts)
  * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
@@ -197,7 +203,7 @@ function get_object_taxonomies($object, $output = 'names') {
  *
  * @since 2.3.0
  *
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
  *
  * @param string $taxonomy Name of taxonomy object to return
  * @return object|bool The Taxonomy Object or false if $taxonomy doesn't exist
@@ -218,7 +224,7 @@ function get_taxonomy( $taxonomy ) {
  *
  * @since 3.0.0
  *
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
  *
  * @param string $taxonomy Name of taxonomy object
  * @return bool Whether the taxonomy exists.
@@ -464,6 +470,7 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
  * Above, the first default value is for non-hierarchical taxonomies (like tags) and the second one is for hierarchical taxonomies (like categories).
  *
  * @since 3.0.0
+ *
  * @param object $tax Taxonomy object
  * @return object object with all the labels as member variables
  */
@@ -504,7 +511,8 @@ function get_taxonomy_labels( $tax ) {
  * Add an already registered taxonomy to an object type.
  *
  * @since 3.0.0
- * @uses $wp_taxonomies Modifies taxonomy object
+ *
+ * @global array $wp_taxonomies The registered taxonomies.
  *
  * @param string $taxonomy Name of taxonomy object
  * @param string $object_type Name of the object type
@@ -530,6 +538,8 @@ function register_taxonomy_for_object_type( $taxonomy, $object_type) {
  *
  * @since 3.7.0
  *
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
  * @param string $taxonomy    Name of taxonomy object.
  * @param string $object_type Name of the object type.
  * @return bool True if successful, false if not.
@@ -1001,6 +1011,8 @@ class WP_Tax_Query {
 	 * @since 4.1.0
 	 * @access public
 	 *
+	 * @global wpdb $wpdb The WordPress database abstraction object.
+	 *
 	 * @param array $clause       Query clause, passed by reference
 	 * @param array $parent_query Parent query array.
 	 * @return array {
@@ -1209,6 +1221,8 @@ class WP_Tax_Query {
 	 *
 	 * @since 3.2.0
 	 *
+	 * @global wpdb $wpdb The WordPress database abstraction object.
+	 *
 	 * @param array  &$query          The single query.
 	 * @param string $resulting_field The resulting field. Accepts 'slug', 'name', 'term_taxonomy_id',
 	 *                                or 'term_id'. Default: 'term_id'.
@@ -1461,8 +1475,6 @@ function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw
  *
  * @since 2.3.0
  *
- * @global wpdb $wpdb WordPress database abstraction object.
- *
  * @param string $term_id ID of Term to get children
  * @param string $taxonomy Taxonomy Name
  * @return array|WP_Error List of Term IDs. WP_Error returned if $taxonomy does not exist
@@ -3052,6 +3064,8 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
  *
  * @since 2.3.0
  *
+ * @global wpdb $wpdb The WordPress database abstraction object.
+ *
  * @param int              $object_id The object to relate to.
  * @param array|int|string $terms     A single term slug, single term id, or array of either term slugs or ids.
  *                                    Will replace all existing related terms in this taxonomy.