Docs: Add and correct `@since` docs for a variety of functions and methods.

Props keesiemeijer, chris_dev
Fixes #39343, #39357, #39344
See #39130

Built from https://develop.svn.wordpress.org/trunk@39638


git-svn-id: http://core.svn.wordpress.org/trunk@39578 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/author-template.php

@@ -183,6 +183,8 @@ function the_author_meta( $field = '', $user_id = false ) {
  * If the author has a home page set, return an HTML link, otherwise just return the
  * author's name.
  *
+ * @since 3.0.0
+ *
  * @return string|null An HTML link if the author's url exist in user meta,
  *                     else the result of get_the_author().
  */
@@ -502,6 +504,8 @@ function is_multi_author() {
 /**
  * Helper function to clear the cache for number of authors.
  *
+ * @since 3.2.0
+ *
  * @private
  */
 function __clear_multi_author_cache() {

wp-includes/category-template.php

@@ -720,8 +720,10 @@ function wp_tag_cloud( $args = '' ) {
 /**
  * Default topic count scaling for tag links
  *
- * @param int $count number of posts with that tag
- * @return int scaled count
+ * @since 2.9.0
+ *
+ * @param int $count Number of posts with that tag.
+ * @return int Scaled count.
  */
 function default_topic_count_scale( $count ) {
 	return round(log10($count + 1) * 100);

wp-includes/functions.php

@@ -1921,6 +1921,7 @@ function wp_upload_dir( $time = null, $create_dir = true, $refresh_cache = false
 /**
  * A non-filtered, non-cached version of wp_upload_dir() that doesn't check the path.
  *
+ * @since 4.5.0
  * @access private
  *
  * @param string $time Optional. Time formatted in 'yyyy/mm'. Default null.
@@ -5108,6 +5109,8 @@ function _device_can_upload() {
 /**
  * Test if a given path is a stream URL
  *
+ * @since 3.5.0
+ *
  * @param string $path The resource path or URL.
  * @return bool True if the path is a stream URL.
  */

wp-includes/general-template.php

@@ -808,7 +808,7 @@ function get_site_icon_url( $size = 512, $url = '', $blog_id = 0 ) {
 	/**
 	 * Filters the site icon URL.
 	 *
-	 * @site 4.4.0
+	 * @since 4.4.0
 	 *
 	 * @param string $url     Site icon URL.
 	 * @param int    $size    Size of the site icon.

wp-includes/kses.php

@@ -1449,6 +1449,7 @@ function wp_kses_normalize_entities2($matches) {
  * This function helps wp_kses_normalize_entities() to only accept valid Unicode
  * numeric entities in hex form.
  *
+ * @since 2.7.0
  * @access private
  *
  * @param array $matches preg_replace_callback() matches array
@@ -1465,6 +1466,8 @@ function wp_kses_normalize_entities3($matches) {
 /**
  * Helper function to determine if a Unicode value is valid.
  *
+ * @since 2.7.0
+ *
  * @param int $i Unicode value
  * @return bool True if the value was a valid Unicode number
  */
@@ -1497,6 +1500,8 @@ function wp_kses_decode_entities($string) {
 /**
  * Regex callback for wp_kses_decode_entities()
  *
+ * @since 2.9.0
+ *
  * @param array $match preg match
  * @return string
  */
@@ -1507,6 +1512,8 @@ function _wp_kses_decode_entities_chr( $match ) {
 /**
  * Regex callback for wp_kses_decode_entities()
  *
+ * @since 2.9.0
+ *
  * @param array $match preg match
  * @return string
  */

wp-includes/media.php

@@ -1045,6 +1045,8 @@ function wp_calculate_image_srcset( $size_array, $image_src, $image_meta, $attac
 	/**
 	 * Let plugins pre-filter the image meta to be able to fix inconsistencies in the stored data.
 	 *
+	 * @since 4.5.0
+	 *
 	 * @param array  $image_meta    The image meta data as returned by 'wp_get_attachment_metadata()'.
 	 * @param array  $size_array    Array of width and height values in pixels (in that order).
 	 * @param string $image_src     The 'src' of the image.

wp-includes/ms-functions.php

@@ -2242,7 +2242,7 @@ function wp_schedule_update_network_counts() {
 /**
  *  Update the network-wide counts for the current network.
  *
- *  @since 3.1.0
+ * @since 3.1.0
  */
 function wp_update_network_counts() {
 	wp_update_network_user_counts();

wp-includes/nav-menu.php

@@ -96,6 +96,7 @@ function register_nav_menus( $locations = array() ) {
 /**
  * Unregisters a navigation menu location for a theme.
  *
+ * @since 3.1.0
  * @global array $_wp_registered_nav_menus
  *
  * @param string $location The menu location identifier.

wp-includes/rest-api.php

@@ -988,6 +988,8 @@ function rest_get_avatar_sizes() {
 /**
  * Validate a value based on a schema.
  *
+ * @since 4.7.0
+ *
  * @param mixed  $value The value to validate.
  * @param array  $args  Schema array to use for validation.
  * @param string $param The parameter name, used in error messages.
@@ -1110,6 +1112,8 @@ function rest_validate_value_from_schema( $value, $args, $param = '' ) {
 /**
  * Sanitize a value based on a schema.
  *
+ * @since 4.7.0
+ *
  * @param mixed $value The value to sanitize.
  * @param array $args  Schema array to use for sanitization.
  * @return true|WP_Error

wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

@@ -1518,6 +1518,8 @@ class WP_REST_Posts_Controller extends WP_REST_Controller {
 	 * "Protected: %s", as the REST API communicates the protected status of a post
 	 * in a machine readable format, we remove the "Protected: " prefix.
 	 *
+	 * @since 4.7.0
+	 *
 	 * @return string Protected title format.
 	 */
 	public function protected_title_format() {

wp-includes/rest-api/endpoints/class-wp-rest-settings-controller.php

@@ -305,6 +305,8 @@ class WP_REST_Settings_Controller extends WP_REST_Controller {
 	 * `null` as it's not a valid value for something like "type => string". We
 	 * provide a wrapper sanitizer to whitelist the use of `null`.
 	 *
+	 * @since 4.7.0
+	 *
 	 * @param  mixed           $value   The value for the setting.
 	 * @param  WP_REST_Request $request The request object.
 	 * @param  string          $param   The parameter name.

wp-includes/vars.php

@@ -120,6 +120,8 @@ $is_iis7 = $is_IIS && intval( substr( $_SERVER['SERVER_SOFTWARE'], strpos( $_SER
 /**
  * Test if the current browser runs on a mobile device (smart phone, tablet, etc.)
  *
+ * @since 3.4.0
+ * 
  * @return bool
  */
 function wp_is_mobile() {

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.8-alpha-39637';
+$wp_version = '4.8-alpha-39638';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.