Docs: Various docblock improvements.

See #51800

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


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

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

@@ -40,7 +40,7 @@ final class WP_Post_Type {
 	 * @see get_post_type_labels()
 	 *
 	 * @since 4.6.0
-	 * @var object $labels
+	 * @var stdClass $labels
 	 */
 	public $labels;
 
@@ -158,7 +158,7 @@ final class WP_Post_Type {
 	public $menu_position = null;
 
 	/**
-	 * The URL to the icon to be used for this menu.
+	 * The URL or reference to the icon to be used for this menu.
 	 *
 	 * Pass a base64-encoded SVG using a data URI, which will be colored to match the color scheme.
 	 * This should begin with 'data:image/svg+xml;base64,'. Pass the name of a Dashicons helper class
@@ -317,7 +317,7 @@ final class WP_Post_Type {
 	 * Post type capabilities.
 	 *
 	 * @since 4.6.0
-	 * @var object $cap
+	 * @var stdClass $cap
 	 */
 	public $cap;
 
@@ -381,6 +381,8 @@ final class WP_Post_Type {
 	/**
 	 * Constructor.
 	 *
+	 * See the register_post_type() function for accepted arguments for `$args`.
+	 *
 	 * Will populate object properties from the provided arguments and assign other
 	 * default properties based on that information.
 	 *
@@ -401,6 +403,8 @@ final class WP_Post_Type {
 	/**
 	 * Sets post type properties.
 	 *
+	 * See the register_post_type() function for accepted arguments for `$args`.
+	 *
 	 * @since 4.6.0
 	 *
 	 * @param array|string $args Array or string of arguments for registering a post type.
@@ -414,6 +418,7 @@ final class WP_Post_Type {
 		 * @since 4.4.0
 		 *
 		 * @param array  $args      Array of arguments for registering a post type.
+		 *                          See the register_post_type() function for accepted arguments.
 		 * @param string $post_type Post type key.
 		 */
 		$args = apply_filters( 'register_post_type_args', $args, $this->name );

wp-includes/class-wp-taxonomy.php

@@ -38,7 +38,7 @@ final class WP_Taxonomy {
 	 * @see get_taxonomy_labels()
 	 *
 	 * @since 4.7.0
-	 * @var object
+	 * @var stdClass
 	 */
 	public $labels;
 
@@ -152,7 +152,7 @@ final class WP_Taxonomy {
 	 * Capabilities for this taxonomy.
 	 *
 	 * @since 4.7.0
-	 * @var object
+	 * @var stdClass
 	 */
 	public $cap;
 
@@ -239,6 +239,8 @@ final class WP_Taxonomy {
 	/**
 	 * Constructor.
 	 *
+	 * See the register_taxonomy() function for accepted arguments for `$args`.
+	 *
 	 * @since 4.7.0
 	 *
 	 * @global WP $wp Current WordPress environment instance.
@@ -257,6 +259,8 @@ final class WP_Taxonomy {
 	/**
 	 * Sets taxonomy properties.
 	 *
+	 * See the register_taxonomy() function for accepted arguments for `$args`.
+	 *
 	 * @since 4.7.0
 	 *
 	 * @param array|string $object_type Name of the object type for the taxonomy object.
@@ -271,6 +275,7 @@ final class WP_Taxonomy {
 		 * @since 4.4.0
 		 *
 		 * @param array    $args        Array of arguments for registering a taxonomy.
+		 *                              See the register_taxonomy() function for accepted arguments.
 		 * @param string   $taxonomy    Taxonomy key.
 		 * @param string[] $object_type Array of names of object types for the taxonomy.
 		 */

wp-includes/class-wp-user.php

@@ -40,7 +40,7 @@ class WP_User {
 	 * User data container.
 	 *
 	 * @since 2.0.0
-	 * @var object
+	 * @var stdClass
 	 */
 	public $data;
 

wp-includes/functions.php

@@ -1178,7 +1178,7 @@ function remove_query_arg( $key, $query = false ) {
  *
  * @since 4.4.0
  *
- * @return string[] An array of parameters to remove from the URL.
+ * @return string[] An array of query variable names to remove from the URL.
  */
 function wp_removable_query_args() {
 	$removable_query_args = array(
@@ -1213,11 +1213,11 @@ function wp_removable_query_args() {
 	);
 
 	/**
-	 * Filters the list of query variables to remove.
+	 * Filters the list of query variable names to remove.
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param string[] $removable_query_args An array of query variables to remove from a URL.
+	 * @param string[] $removable_query_args An array of query variable names to remove from a URL.
 	 */
 	return apply_filters( 'removable_query_args', $removable_query_args );
 }

wp-includes/pomo/plural-forms.php

@@ -91,6 +91,8 @@ if ( ! class_exists( 'Plural_Forms', false ) ) :
 		 *
 		 * @since 4.9.0
 		 *
+		 * @throws Exception If there is a syntax or parsing error with the string.
+		 *
 		 * @param string $str String to parse.
 		 */
 		protected function parse( $str ) {
@@ -250,6 +252,8 @@ if ( ! class_exists( 'Plural_Forms', false ) ) :
 		 *
 		 * @since 4.9.0
 		 *
+		 * @throws Exception If the plural form value cannot be calculated.
+		 *
 		 * @param int $n Variable "n" to substitute.
 		 * @return int Plural form value.
 		 */

wp-includes/post.php

@@ -5508,7 +5508,9 @@ function get_page_uri( $page = 0 ) {
  *     @type string|array $post_status  A comma-separated list or array of post statuses to include.
  *                                      Default 'publish'.
  * }
- * @return array|false Array of pages matching defaults or `$args`.
+ * @return WP_Post[]|int[]|false Array of pages (or hierarchical post type items). Boolean false if the
+ *                               specified post type is not hierarchical or the specified status is not
+ *                               supported by the post type.
  */
 function get_pages( $args = array() ) {
 	global $wpdb;

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

@@ -266,7 +266,15 @@ class WP_REST_Posts_Controller extends WP_REST_Controller {
 		$args['post_type'] = $this->post_type;
 
 		/**
-		 * Filters the query arguments for a request.
+		 * Filters WP_Query arguments when querying users via the REST API.
+		 *
+		 * The dynamic portion of the hook name, `$this->post_type`, refers to the post type slug.
+		 *
+		 * Possible filter names include:
+		 *
+		 *  - `rest_post_query`
+		 *  - `rest_page_query`
+		 *  - `rest_attachment_query`
 		 *
 		 * Enables adding extra arguments or setting defaults for a post collection request.
 		 *
@@ -274,8 +282,8 @@ class WP_REST_Posts_Controller extends WP_REST_Controller {
 		 *
 		 * @link https://developer.wordpress.org/reference/classes/wp_query/
 		 *
-		 * @param array           $args    Key value array of query var to query value.
+		 * @param array           $args    Array of arguments to be passed to WP_Query.
-		 * @param WP_REST_Request $request The request used.
+		 * @param WP_REST_Request $request The REST API request.
 		 */
 		$args       = apply_filters( "rest_{$this->post_type}_query", $args, $request );
 		$query_args = $this->prepare_items_query( $args, $request );

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

@@ -233,7 +233,7 @@ class WP_REST_Terms_Controller extends WP_REST_Controller {
 		}
 
 		/**
-		 * Filters the query arguments before passing them to get_terms().
+		 * Filters get_terms() arguments when querying users via the REST API.
 		 *
 		 * The dynamic portion of the hook name, `$this->taxonomy`, refers to the taxonomy slug.
 		 *
@@ -246,7 +246,7 @@ class WP_REST_Terms_Controller extends WP_REST_Controller {
 		 *
 		 * @param array           $prepared_args Array of arguments to be
 		 *                                       passed to get_terms().
-		 * @param WP_REST_Request $request       The current request.
+		 * @param WP_REST_Request $request       The REST API request.
 		 */
 		$prepared_args = apply_filters( "rest_{$this->taxonomy}_query", $prepared_args, $request );
 

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

@@ -312,7 +312,7 @@ class WP_REST_Users_Controller extends WP_REST_Controller {
 		 * @since 4.7.0
 		 *
 		 * @param array           $prepared_args Array of arguments for WP_User_Query.
-		 * @param WP_REST_Request $request       The current request.
+		 * @param WP_REST_Request $request       The REST API request.
 		 */
 		$prepared_args = apply_filters( 'rest_user_query', $prepared_args, $request );
 

wp-includes/taxonomy.php

@@ -2195,8 +2195,12 @@ function wp_get_object_terms( $object_ids, $taxonomies, $args = array() ) {
  *     @type int    $parent      The id of the parent term. Default 0.
  *     @type string $slug        The term slug to use. Default empty string.
  * }
- * @return array|WP_Error An array containing the `term_id` and `term_taxonomy_id`,
+ * @return array|WP_Error {
- *                        WP_Error otherwise.
+ *     An array of the new term data, WP_Error otherwise.
+ *
+ *     @type int        $term_id          The new term ID.
+ *     @type int|string $term_taxonomy_id The new term taxonomy ID. Can be a numeric string.
+ * }
  */
 function wp_insert_term( $term, $taxonomy, $args = array() ) {
 	global $wpdb;
@@ -3742,7 +3746,7 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array  $terms    List of term objects (passed by reference).
+ * @param object[]|WP_Term[] $terms    List of term objects (passed by reference).
  * @param string             $taxonomy Term context.
  */
 function _pad_term_counts( &$terms, $taxonomy ) {

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.7-alpha-49789';
+$wp_version = '5.7-alpha-49790';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/widgets.php

@@ -802,19 +802,19 @@ function dynamic_sidebar( $index = 1 ) {
 		 *
 		 * @since 3.0.0
 		 *
-		 * @param array $widget_id {
+		 * @param array $widget {
 		 *     An associative array of widget arguments.
 		 *
 		 *     @type string   $name        Name of the widget.
 		 *     @type string   $id          Widget ID.
-		 *     @type callable $callback    When the hook is fired on the front end, $callback is an array
+		 *     @type callable $callback    When the hook is fired on the front end, `$callback` is an array
-		 *                                 containing the widget object. Fired on the back end, $callback
+		 *                                 containing the widget object. Fired on the back end, `$callback`
-		 *                                 is 'wp_widget_control', see $_callback.
+		 *                                 is 'wp_widget_control', see `$_callback`.
 		 *     @type array    $params      An associative array of multi-widget arguments.
 		 *     @type string   $classname   CSS class applied to the widget container.
 		 *     @type string   $description The widget description.
-		 *     @type array    $_callback   When the hook is fired on the back end, $_callback is populated
+		 *     @type array    $_callback   When the hook is fired on the back end, `$_callback` is populated
-		 *                                 with an array containing the widget object, see $callback.
+		 *                                 with an array containing the widget object, see `$callback`.
 		 * }
 		 */
 		do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] );