Changeset 43177

Timestamp:

05/07/2018 05:19:48 PM (8 years ago)

Author:

johnbillion

Message:

Docs: Update and correct various inline documentation.

See #42505, #41756

Location:

trunk/src

Files:

• wp-admin/includes/list-table.php (modified) (2 diffs)
• wp-admin/includes/ms.php (modified) (1 diff)
• wp-includes/class-wp-post.php (modified) (1 diff)
• wp-includes/post-template.php (modified) (7 diffs)
• wp-includes/taxonomy.php (modified) (1 diff)

trunk/src/wp-admin/includes/list-table.php

@@ -9 +9 @@
 
 /**
- * Fetch an instance of a WP_List_Table class.
+ * Fetches an instance of a WP_List_Table class.
  *
  * @access private
@@ -17 +17 @@
  *
  * @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() ) {

trunk/src/wp-admin/includes/ms.php

@@ -674 +674 @@
 
 /**
- * Synchronize 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'.
+ * Synchronizes category and post tag slugs when global terms are enabled.
+ *
+ * @since 3.0.0
+ *
+ * @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 ) {

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

@@ -353 +353 @@
          *
          * @param string $filter Filter.
-         * @return self|array|bool|object|WP_Post
+         * @return array|bool|object|WP_Post
          */
         public function filter( $filter ) {

trunk/src/wp-includes/post-template.php

@@ -430 +430 @@
 
 /**
- * Display the classes for the post div.
+ * Displays the classes for the post container element.
  *
  * @since 2.7.0
@@ -443 +443 @@
 
 /**
- * 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'
@@ -452 +452 @@
  *
  * 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.
- *
- * @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.
+ * @since 4.2.0 Custom taxonomy class names were added.
+ *
+ * @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 ) {
@@ -553 +553 @@
 
         /**
-         * 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 );
@@ -567 +567 @@
 
 /**
- * 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
@@ -585 +585 @@
  * @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 = '' ) {
@@ -801 +801 @@
 
         /**
-         * 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 );

trunk/src/wp-includes/taxonomy.php

@@ -811 +811 @@
 
         /**
-         * 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.
-         *
-         * @param int|WP_Term $_term    Term object or ID.
-         * @param string      $taxonomy The taxonomy slug.
+         * @since 4.4.0 `$_term` is now a `WP_Term` object.
+         *
+         * @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.
-         *
-         * @param int|WP_Term $_term    Term object or ID.
-         * @param string      $taxonomy The taxonomy slug.
+         * @since 4.4.0 `$_term` is now a `WP_Term` object.
+         *
+         * @param WP_Term $_term    Term object.
+         * @param string  $taxonomy The taxonomy slug.
          */
         $_term = apply_filters( "get_{$taxonomy}", $_term, $taxonomy );