From 1decf42f3a7834f8f4201c7eb83a4a72fb79870f Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Mon, 7 May 2018 17:19:48 +0000 Subject: [PATCH] Docs: Update and correct various inline documentation. See #42505, #41756 git-svn-id: https://develop.svn.wordpress.org/trunk@43177 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/includes/list-table.php | 6 ++-- src/wp-admin/includes/ms.php | 14 +++++----- src/wp-includes/class-wp-post.php | 2 +- src/wp-includes/post-template.php | 42 ++++++++++++++-------------- src/wp-includes/taxonomy.php | 18 ++++++------ 5 files changed, 41 insertions(+), 41 deletions(-) diff --git a/src/wp-admin/includes/list-table.php b/src/wp-admin/includes/list-table.php index 7c6699b274..168aebbd43 100644 --- a/src/wp-admin/includes/list-table.php +++ b/src/wp-admin/includes/list-table.php @@ -8,7 +8,7 @@ */ /** - * Fetch an instance of a WP_List_Table class. + * Fetches an instance of a WP_List_Table class. * * @access private * @since 3.1.0 @@ -16,8 +16,8 @@ * @global string $hook_suffix * * @param string $class The type of the list table, which is the class name. - * @param array $args Optional. Arguments to pass to the class. Accepts 'screen'. - * @return object|bool Object on success, false if the class does not exist. + * @param array $args Optional. Arguments to pass to the class. Accepts 'screen'. + * @return WP_List_Table|bool List table object on success, false if the class does not exist. */ function _get_list_table( $class, $args = array() ) { $core_classes = array( diff --git a/src/wp-admin/includes/ms.php b/src/wp-admin/includes/ms.php index aa12d920a9..f46b7f336e 100644 --- a/src/wp-admin/includes/ms.php +++ b/src/wp-admin/includes/ms.php @@ -673,16 +673,16 @@ function format_code_lang( $code = '' ) { } /** - * Synchronize category and post tag slugs when global terms are enabled. + * Synchronizes category and post tag slugs when global terms are enabled. * * @since 3.0.0 * - * @param object $term The term. - * @param string $taxonomy The taxonomy for `$term`. Should be 'category' or 'post_tag', as these are - * the only taxonomies which are processed by this function; anything else - * will be returned untouched. - * @return object|array Returns `$term`, after filtering the 'slug' field with sanitize_title() - * if $taxonomy is 'category' or 'post_tag'. + * @param WP_Term|array $term The term. + * @param string $taxonomy The taxonomy for `$term`. Should be 'category' or 'post_tag', as these are + * the only taxonomies which are processed by this function; anything else + * will be returned untouched. + * @return WP_Term|array Returns `$term`, after filtering the 'slug' field with `sanitize_title()` + * if `$taxonomy` is 'category' or 'post_tag'. */ function sync_category_tag_slugs( $term, $taxonomy ) { if ( global_terms_enabled() && ( $taxonomy == 'category' || $taxonomy == 'post_tag' ) ) { diff --git a/src/wp-includes/class-wp-post.php b/src/wp-includes/class-wp-post.php index 231fa4cd86..67edf8a07c 100644 --- a/src/wp-includes/class-wp-post.php +++ b/src/wp-includes/class-wp-post.php @@ -352,7 +352,7 @@ final class WP_Post { * @since 3.5.0 * * @param string $filter Filter. - * @return self|array|bool|object|WP_Post + * @return array|bool|object|WP_Post */ public function filter( $filter ) { if ( $this->filter == $filter ) { diff --git a/src/wp-includes/post-template.php b/src/wp-includes/post-template.php index 9cf6c44551..b2c0d300c7 100644 --- a/src/wp-includes/post-template.php +++ b/src/wp-includes/post-template.php @@ -429,7 +429,7 @@ function has_excerpt( $post = 0 ) { } /** - * Display the classes for the post div. + * Displays the classes for the post container element. * * @since 2.7.0 * @@ -442,7 +442,7 @@ function post_class( $class = '', $post_id = null ) { } /** - * Retrieves the classes for the post div as an array. + * Retrieves an array of the class names for the post container element. * * The class names are many. If the post is a sticky, then the 'sticky' * class name. The class 'hentry' is always added to each post. If the post has a @@ -451,16 +451,16 @@ function post_class( $class = '', $post_id = null ) { * eg 'category-foo' or 'my_custom_taxonomy-bar'. * * The 'post_tag' taxonomy is a special - * case; the class has the 'tag-' prefix instead of 'post_tag-'. All classes are - * passed through the filter, {@see 'post_class'}, with the list of classes, followed by + * case; the class has the 'tag-' prefix instead of 'post_tag-'. All class names are + * passed through the filter, {@see 'post_class'}, with the list of class names, followed by * $class parameter value, with the post ID as the last parameter. * * @since 2.7.0 - * @since 4.2.0 Custom taxonomy classes were added. + * @since 4.2.0 Custom taxonomy class names were added. * - * @param string|array $class One or more classes to add to the class list. - * @param int|WP_Post $post_id Optional. Post ID or post object. - * @return array Array of classes. + * @param string|string[] $class Space-separated string or array of class names to add to the class list. + * @param int|WP_Post $post_id Optional. Post ID or post object. + * @return string[] Array of class names. */ function get_post_class( $class = '', $post_id = null ) { $post = get_post( $post_id ); @@ -552,13 +552,13 @@ function get_post_class( $class = '', $post_id = null ) { $classes = array_map( 'esc_attr', $classes ); /** - * Filters the list of CSS classes for the current post. + * Filters the list of CSS class names for the current post. * * @since 2.7.0 * - * @param array $classes An array of post classes. - * @param array $class An array of additional classes added to the post. - * @param int $post_id The post ID. + * @param string[] $classes An array of post class names. + * @param string[] $class An array of additional class names added to the post. + * @param int $post_id The post ID. */ $classes = apply_filters( 'post_class', $classes, $class, $post->ID ); @@ -566,26 +566,26 @@ function get_post_class( $class = '', $post_id = null ) { } /** - * Display the classes for the body element. + * Displays the class names for the body element. * * @since 2.8.0 * - * @param string|array $class One or more classes to add to the class list. + * @param string|string[] $class Space-separated string or array of class names to add to the class list. */ function body_class( $class = '' ) { - // Separates classes with a single space, collates classes for body element + // Separates class names with a single space, collates class names for body element echo 'class="' . join( ' ', get_body_class( $class ) ) . '"'; } /** - * Retrieve the classes for the body element as an array. + * Retrieves an array of the class names for the body element. * * @since 2.8.0 * * @global WP_Query $wp_query * - * @param string|array $class One or more classes to add to the class list. - * @return array Array of classes. + * @param string|string[] $class Space-separated string or array of class names to add to the class list. + * @return string[] Array of class names. */ function get_body_class( $class = '' ) { global $wp_query; @@ -800,12 +800,12 @@ function get_body_class( $class = '' ) { $classes = array_map( 'esc_attr', $classes ); /** - * Filters the list of CSS body classes for the current post or page. + * Filters the list of CSS body class names for the current post or page. * * @since 2.8.0 * - * @param array $classes An array of body classes. - * @param array $class An array of additional classes added to the body. + * @param string[] $classes An array of body class names. + * @param string[] $class An array of additional class names added to the body. */ $classes = apply_filters( 'body_class', $classes, $class ); diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index df828b0fc9..102345fd3c 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -810,27 +810,27 @@ function get_term( $term, $taxonomy = '', $output = OBJECT, $filter = 'raw' ) { } /** - * Filters a term. + * Filters a taxonomy term object. * * @since 2.3.0 - * @since 4.4.0 `$_term` can now also be a WP_Term object. + * @since 4.4.0 `$_term` is now a `WP_Term` object. * - * @param int|WP_Term $_term Term object or ID. - * @param string $taxonomy The taxonomy slug. + * @param WP_Term $_term Term object. + * @param string $taxonomy The taxonomy slug. */ $_term = apply_filters( 'get_term', $_term, $taxonomy ); /** - * Filters a taxonomy. + * Filters a taxonomy term object. * * The dynamic portion of the filter name, `$taxonomy`, refers - * to the taxonomy slug. + * to the slug of the term's taxonomy. * * @since 2.3.0 - * @since 4.4.0 `$_term` can now also be a WP_Term object. + * @since 4.4.0 `$_term` is now a `WP_Term` object. * - * @param int|WP_Term $_term Term object or ID. - * @param string $taxonomy The taxonomy slug. + * @param WP_Term $_term Term object. + * @param string $taxonomy The taxonomy slug. */ $_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );