From d34a21c950ba974c01b3f4ca7de92c04d87bb3c5 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 4 Sep 2020 20:39:47 +0000 Subject: [PATCH] Docs: Various docblock corrections and improvements. See #50768 git-svn-id: https://develop.svn.wordpress.org/trunk@48941 602fd350-edb4-49c9-b593-d223f7449a82 --- .../includes/class-wp-comments-list-table.php | 6 ++--- src/wp-admin/media-upload.php | 2 +- src/wp-includes/category-template.php | 6 +++-- src/wp-includes/class-wp-comment.php | 20 ++++++++++++---- src/wp-includes/class-wp-post.php | 2 +- src/wp-includes/load.php | 2 +- src/wp-includes/post.php | 4 ++-- src/wp-includes/taxonomy.php | 23 ++++++++++++++----- 8 files changed, 44 insertions(+), 21 deletions(-) diff --git a/src/wp-admin/includes/class-wp-comments-list-table.php b/src/wp-admin/includes/class-wp-comments-list-table.php index dd5aa74833..872d101cb0 100644 --- a/src/wp-admin/includes/class-wp-comments-list-table.php +++ b/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', diff --git a/src/wp-admin/media-upload.php b/src/wp-admin/media-upload.php index 22764ce49f..64c524ec66 100644 --- a/src/wp-admin/media-upload.php +++ b/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' ); } diff --git a/src/wp-includes/category-template.php b/src/wp-includes/category-template.php index 46a9c675d0..bfb23264d1 100644 --- a/src/wp-includes/category-template.php +++ b/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 ); } diff --git a/src/wp-includes/class-wp-comment.php b/src/wp-includes/class-wp-comment.php index 3ac8c226e9..68c8be732d 100644 --- a/src/wp-includes/class-wp-comment.php +++ b/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; diff --git a/src/wp-includes/class-wp-post.php b/src/wp-includes/class-wp-post.php index a64a0d346f..e1c3c3bb6f 100644 --- a/src/wp-includes/class-wp-post.php +++ b/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 */ diff --git a/src/wp-includes/load.php b/src/wp-includes/load.php index 8cc14e06db..0cec068fd7 100644 --- a/src/wp-includes/load.php +++ b/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 diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 6b3d9ae42d..c0e5e1fc70 100644 --- a/src/wp-includes/post.php +++ b/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 ); diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index da0744e674..cc491a87dd 100644 --- a/src/wp-includes/taxonomy.php +++ b/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 - * by the parent function. WP_Error otherwise. + * @param WP_Term $deleted_term Copy of the already-deleted term. * @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 - * by the parent function. WP_Error otherwise. + * @param WP_Term $deleted_term Copy of the already-deleted term. * @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.