From bf83c368fdfcee2b879d00b193f505038e1681f0 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Thu, 10 Dec 2020 23:59:03 +0000 Subject: [PATCH] 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 | 11 ++++++++--- wp-includes/class-wp-taxonomy.php | 9 +++++++-- wp-includes/class-wp-user.php | 2 +- wp-includes/functions.php | 6 +++--- wp-includes/pomo/plural-forms.php | 4 ++++ wp-includes/post.php | 4 +++- .../endpoints/class-wp-rest-posts-controller.php | 14 +++++++++++--- .../endpoints/class-wp-rest-terms-controller.php | 4 ++-- .../endpoints/class-wp-rest-users-controller.php | 2 +- wp-includes/taxonomy.php | 12 ++++++++---- wp-includes/version.php | 2 +- wp-includes/widgets.php | 12 ++++++------ 12 files changed, 55 insertions(+), 27 deletions(-) diff --git a/wp-includes/class-wp-post-type.php b/wp-includes/class-wp-post-type.php index 53d45d8a08..43e8a61514 100644 --- a/wp-includes/class-wp-post-type.php +++ b/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 ); diff --git a/wp-includes/class-wp-taxonomy.php b/wp-includes/class-wp-taxonomy.php index c34a03c38e..9c6c1d7caa 100644 --- a/wp-includes/class-wp-taxonomy.php +++ b/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. */ diff --git a/wp-includes/class-wp-user.php b/wp-includes/class-wp-user.php index 16f4a52c7f..87518c45c8 100644 --- a/wp-includes/class-wp-user.php +++ b/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; diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 7219d768a9..f5d355a632 100644 --- a/wp-includes/functions.php +++ b/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 ); } diff --git a/wp-includes/pomo/plural-forms.php b/wp-includes/pomo/plural-forms.php index 73477b454b..2ed0c62ebf 100644 --- a/wp-includes/pomo/plural-forms.php +++ b/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. */ diff --git a/wp-includes/post.php b/wp-includes/post.php index 87806adfca..9f360e3391 100644 --- a/wp-includes/post.php +++ b/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; diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php index a052d04964..30cb8f69fa 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php +++ b/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 WP_REST_Request $request The request used. + * @param array $args Array of arguments to be passed to WP_Query. + * @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 ); diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php index 3284017cdc..d2aea69363 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-terms-controller.php +++ b/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 ); diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php index cac342661b..7220774e7e 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php +++ b/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 ); diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 98346ea6ae..f6eefe0069 100644 --- a/wp-includes/taxonomy.php +++ b/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`, - * WP_Error otherwise. + * @return array|WP_Error { + * 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,8 +3746,8 @@ 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 string $taxonomy Term context. + * @param object[]|WP_Term[] $terms List of term objects (passed by reference). + * @param string $taxonomy Term context. */ function _pad_term_counts( &$terms, $taxonomy ) { global $wpdb; diff --git a/wp-includes/version.php b/wp-includes/version.php index c6b97c9a53..a86a57ebfa 100644 --- a/wp-includes/version.php +++ b/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. diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index db06222a51..8c5ddc2762 100644 --- a/wp-includes/widgets.php +++ b/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 - * containing the widget object. Fired on the back end, $callback - * is 'wp_widget_control', see $_callback. + * @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` + * 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 - * with an array containing the widget object, see $callback. + * @type array $_callback When the hook is fired on the back end, `$_callback` is populated + * with an array containing the widget object, see `$callback`. * } */ do_action( 'dynamic_sidebar', $wp_registered_widgets[ $id ] );