Docs: Various docblock corrections and improvements.

See #50768

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

src/wp-admin/includes/class-wp-comments-list-table.php

@@ -472,7 +472,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * Displays a comment status drop-down for filtering on the Comments list table.
+	 * Displays a comment type drop-down for filtering on the Comments list table.
 	 *
 	 * @since 5.5.0
 	 *
@@ -480,11 +480,11 @@ class WP_Comments_List_Table extends WP_List_Table {
 	 */
 	protected function comment_status_dropdown( $comment_type ) {
 		/**
-		 * Filters the comment types dropdown menu.
+		 * Filters the comment types shown in the drop-down menu on the Comments list table.
 		 *
 		 * @since 2.7.0
 		 *
-		 * @param array $comment_types An array of comment types. Accepts 'Comments', 'Pings'.
+		 * @param string[] $comment_types Array of comment type labels keyed by their name.
 		 */
 		$comment_types = apply_filters(
 			'admin_comment_types_dropdown',

src/wp-admin/media-upload.php

@@ -73,7 +73,7 @@ if ( isset( $_GET['tab'] ) ) {
 	 *
 	 * @since 2.5.0
 	 *
-	 * @param string $type The default media popup tab. Default 'type' (From Computer).
+	 * @param string $tab The default media popup tab. Default 'type' (From Computer).
 	 */
 	$tab = apply_filters( 'media_upload_default_tab', 'type' );
 }

src/wp-includes/category-template.php

@@ -1153,7 +1153,8 @@ function get_tag_link( $tag ) {
  * @since 2.3.0
  *
  * @param int $post_id Post ID.
- * @return array|false|WP_Error Array of tag objects on success, false on failure.
+ * @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
+ *                                  or the post does not exist, WP_Error on failure.
  */
 function get_the_tags( $post_id = 0 ) {
 	$terms = get_the_terms( $post_id, 'post_tag' );
@@ -1165,7 +1166,8 @@ function get_the_tags( $post_id = 0 ) {
 	 *
 	 * @see get_the_terms()
 	 *
-	 * @param WP_Term[] $terms An array of tags for the given post.
+	 * @param WP_Term[]|false|WP_Error $terms Array of WP_Term objects on success, false if there are no terms
+	 *                                        or the post does not exist, WP_Error on failure.
 	 */
 	return apply_filters( 'get_the_tags', $terms );
 }

src/wp-includes/class-wp-comment.php

@@ -17,16 +17,20 @@ final class WP_Comment {
 	/**
 	 * Comment ID.
 	 *
+	 * A numeric string, for compatibility reasons.
+	 *
 	 * @since 4.4.0
-	 * @var int
+	 * @var string
 	 */
 	public $comment_ID;
 
 	/**
 	 * ID of the post the comment is associated with.
 	 *
+	 * A numeric string, for compatibility reasons.
+	 *
 	 * @since 4.4.0
-	 * @var int
+	 * @var string
 	 */
 	public $comment_post_ID = 0;
 
@@ -89,8 +93,10 @@ final class WP_Comment {
 	/**
 	 * Comment karma count.
 	 *
+	 * A numeric string, for compatibility reasons.
+	 *
 	 * @since 4.4.0
-	 * @var int
+	 * @var string
 	 */
 	public $comment_karma = 0;
 
@@ -122,16 +128,20 @@ final class WP_Comment {
 	/**
 	 * Parent comment ID.
 	 *
+	 * A numeric string, for compatibility reasons.
+	 *
 	 * @since 4.4.0
-	 * @var int
+	 * @var string
 	 */
 	public $comment_parent = 0;
 
 	/**
 	 * Comment author ID.
 	 *
+	 * A numeric string, for compatibility reasons.
+	 *
 	 * @since 4.4.0
-	 * @var int
+	 * @var string
 	 */
 	public $user_id = 0;
 

src/wp-includes/class-wp-post.php

@@ -14,7 +14,7 @@
  *
  * @property string $page_template
  *
- * @property-read array  $ancestors
+ * @property-read int[]  $ancestors
  * @property-read int    $post_category
  * @property-read string $tag_input
  */

src/wp-includes/load.php

@@ -134,7 +134,7 @@ function wp_check_php_mysql_versions() {
  * The type can be set via the `WP_ENVIRONMENT_TYPE` global system variable,
  * or a constant of the same name.
  *
- * Possible values include 'local', 'development', 'staging', 'production'.
+ * Possible values are 'local', 'development', 'staging', and 'production'.
  * If not set, the type defaults to 'production'.
  *
  * @since 5.5.0

src/wp-includes/post.php

@@ -796,12 +796,12 @@ function get_post( $post = null, $output = OBJECT, $filter = 'raw' ) {
 }
 
 /**
- * Retrieve ancestors of a post.
+ * Retrieves the IDs of the ancestors of a post.
  *
  * @since 2.5.0
  *
  * @param int|WP_Post $post Post ID or post object.
- * @return int[] Ancestor IDs or empty array if none are found.
+ * @return int[] Array of ancestor IDs or empty array if there are none.
  */
 function get_post_ancestors( $post ) {
 	$post = get_post( $post );

src/wp-includes/taxonomy.php

@@ -886,6 +886,9 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) {
 	/**
 	 * Filters a taxonomy term object.
 	 *
+	 * The {@see 'get_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
+	 *
 	 * @since 2.3.0
 	 * @since 4.4.0 `$_term` is now a `WP_Term` object.
 	 *
@@ -1986,14 +1989,16 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) {
 	/**
 	 * Fires after a term is deleted from the database and the cache is cleaned.
 	 *
+	 * The {@see 'delete_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
+	 *
 	 * @since 2.5.0
 	 * @since 4.5.0 Introduced the `$object_ids` argument.
 	 *
 	 * @param int     $term         Term ID.
 	 * @param int     $tt_id        Term taxonomy ID.
 	 * @param string  $taxonomy     Taxonomy slug.
-	 * @param mixed   $deleted_term Copy of the already-deleted term, in the form specified
+	 * @param WP_Term $deleted_term Copy of the already-deleted term.
-	 *                              by the parent function. WP_Error otherwise.
 	 * @param array   $object_ids   List of term object IDs.
 	 */
 	do_action( 'delete_term', $term, $tt_id, $taxonomy, $deleted_term, $object_ids );
@@ -2009,8 +2014,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) {
 	 *
 	 * @param int     $term         Term ID.
 	 * @param int     $tt_id        Term taxonomy ID.
-	 * @param mixed   $deleted_term Copy of the already-deleted term, in the form specified
+	 * @param WP_Term $deleted_term Copy of the already-deleted term.
-	 *                              by the parent function. WP_Error otherwise.
 	 * @param array   $object_ids   List of term object IDs.
 	 */
 	do_action( "delete_{$taxonomy}", $term, $tt_id, $deleted_term, $object_ids );
@@ -2181,7 +2185,7 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
  * @param string       $term     The term name to add.
  * @param string       $taxonomy The taxonomy to which to add the term.
  * @param array|string $args {
- *     Optional. Array or string of arguments for inserting a term.
+ *     Optional. Array or query string of arguments for inserting a term.
  *
  *     @type string $alias_of    Slug of the term to make this term an alias of.
  *                               Default empty string. Accepts a term slug.
@@ -3104,7 +3108,8 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
 	}
 
 	/**
-	 * Fires immediately after the given terms are edited.
+	 * Fires immediately after a term is updated in the database, but before its
+	 * term-taxonomy relationship is updated.
 	 *
 	 * @since 2.9.0
 	 *
@@ -3138,6 +3143,9 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
 	/**
 	 * Fires after a term has been updated, but before the term cache has been cleaned.
 	 *
+	 * The {@see 'edit_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
+	 *
 	 * @since 2.3.0
 	 *
 	 * @param int    $term_id  Term ID.
@@ -3167,6 +3175,9 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
 	/**
 	 * Fires after a term has been updated, and the term cache has been cleaned.
 	 *
+	 * The {@see 'edited_$taxonomy'} hook is also available for targeting a specific
+	 * taxonomy.
+	 *
 	 * @since 2.3.0
 	 *
 	 * @param int    $term_id  Term ID.