From a3e674d4f9a212faa47185dff6e82bb4f8aaaac0 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Wed, 18 Dec 2019 00:17:54 +0000 Subject: [PATCH] Docs: Various documentation fixes for unit test factories. See #48303. git-svn-id: https://develop.svn.wordpress.org/trunk@46985 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-includes/post.php | 2 +- src/wp-includes/taxonomy.php | 2 +- .../class-wp-unittest-factory-for-attachment.php | 4 ++-- .../class-wp-unittest-factory-for-blog.php | 14 +++++++------- .../class-wp-unittest-factory-for-comment.php | 14 +++++++------- .../class-wp-unittest-factory-for-post.php | 10 +++++----- .../class-wp-unittest-factory-for-term.php | 16 ++++++++-------- .../class-wp-unittest-factory-for-thing.php | 6 +++--- .../class-wp-unittest-factory-for-user.php | 12 ++++++------ 9 files changed, 40 insertions(+), 40 deletions(-) diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php index 1fd84bc2c5..2be10a1db6 100644 --- a/src/wp-includes/post.php +++ b/src/wp-includes/post.php @@ -4150,7 +4150,7 @@ function wp_insert_post( $postarr, $wp_error = false ) { * @param array|object $postarr Optional. Post data. Arrays are expected to be escaped, * objects are not. Default array. * @param bool $wp_error Optional. Allow return of WP_Error on failure. Default false. - * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success. + * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure. */ function wp_update_post( $postarr = array(), $wp_error = false ) { if ( is_object( $postarr ) ) { diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php index a25206759b..a6adef3035 100644 --- a/src/wp-includes/taxonomy.php +++ b/src/wp-includes/taxonomy.php @@ -809,7 +809,7 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) { * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to * a WP_Term object, an associative array, or a numeric array, respectively. Default OBJECT. * @param string $filter Optional, default is raw or no WordPress defined filter will applied. - * @return array|WP_Term|WP_Error|null Object of the type specified by `$output` on success. When `$output` is 'OBJECT', + * @return WP_Term|array|WP_Error|null Object of the type specified by `$output` on success. When `$output` is 'OBJECT', * a WP_Term instance is returned. If taxonomy does not exist, a WP_Error is * returned. Returns null for miscellaneous failure. */ diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php index 98f1be8fde..f8ed1100fe 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-attachment.php @@ -14,7 +14,7 @@ class WP_UnitTest_Factory_For_Attachment extends WP_UnitTest_Factory_For_Post { * @param int $legacy_parent Deprecated. * @param array $legacy_args Deprecated. * - * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure. + * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure. */ public function create_object( $args, $legacy_parent = 0, $legacy_args = array() ) { // Backward compatibility for legacy argument format. @@ -40,7 +40,7 @@ class WP_UnitTest_Factory_For_Attachment extends WP_UnitTest_Factory_For_Post { * Saves an attachment. * * @param string $file The file name to create attachment object for. - * @param int $parent The post id to attach the file to. + * @param int $parent ID of the post to attach the file to. * * @return int|WP_Error The attachment ID on success. The value 0 or WP_Error on failure. */ diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php index 68d24d30bb..ba6b9bba4d 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php @@ -24,11 +24,11 @@ class WP_UnitTest_Factory_For_Blog extends WP_UnitTest_Factory_For_Thing { } /** - * Creates a blog object. + * Creates a site object. * * @param array $args Arguments for the site object. * - * @return int|WP_Error Returns WP_Error object on failure, the site ID on success. + * @return int|WP_Error The site ID on success, WP_Error object on failure. */ public function create_object( $args ) { global $wpdb; @@ -46,9 +46,9 @@ class WP_UnitTest_Factory_For_Blog extends WP_UnitTest_Factory_For_Thing { } /** - * Updates a blog object. Not implemented. + * Updates a site object. Not implemented. * - * @param int $blog_id The blog id to update. + * @param int $blog_id ID of the site to update. * @param array $fields The fields to update. * * @return void @@ -56,11 +56,11 @@ class WP_UnitTest_Factory_For_Blog extends WP_UnitTest_Factory_For_Thing { public function update_object( $blog_id, $fields ) {} /** - * Retrieves a site by given blog id. + * Retrieves a site by a given ID. * - * @param int $blog_id The blog id to retrieve. + * @param int $blog_id ID of the site to retrieve. * - * @return null|WP_Site The site object or null if not found. + * @return WP_Site|null The site object on success, null on failure. */ public function get_object_by_id( $blog_id ) { return get_site( $blog_id ); diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php index dcec0439aa..7f504f7b3b 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php @@ -36,7 +36,7 @@ class WP_UnitTest_Factory_For_Comment extends WP_UnitTest_Factory_For_Thing { /** * Updates a comment. * - * @param int $comment_id The comment id. + * @param int $comment_id The comment ID. * @param array $fields The comment details. * * @return int When updated 1, not update 0. @@ -47,14 +47,14 @@ class WP_UnitTest_Factory_For_Comment extends WP_UnitTest_Factory_For_Thing { } /** - * Creates multiple comments on given post. + * Creates multiple comments on a given post. * - * @param int $post_id The post id to create comments for. + * @param int $post_id ID of the post to create comments for. * @param int $count Total amount of comments to create. * @param array $args The comment details. * @param null $generation_definitions Default values. * - * @return int[] Array with the comment ids. + * @return int[] Array with the comment IDs. */ public function create_post_comments( $post_id, $count = 1, $args = array(), $generation_definitions = null ) { $args['comment_post_ID'] = $post_id; @@ -62,11 +62,11 @@ class WP_UnitTest_Factory_For_Comment extends WP_UnitTest_Factory_For_Thing { } /** - * Returns a comment. + * Retrieves a comment by a given ID. * - * @param int $comment_id The comment id. + * @param int $comment_id ID of the comment to retrieve. * - * @return null|WP_Comment WP_Comment when found, null when not found. + * @return WP_Comment|null WP_Comment object on success, null on failure. */ public function get_object_by_id( $comment_id ) { return get_comment( $comment_id ); diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php index af71802d5f..2ea054bc41 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php @@ -37,10 +37,10 @@ class WP_UnitTest_Factory_For_Post extends WP_UnitTest_Factory_For_Thing { /** * Updates an existing post object. * - * @param int $post_id The post id to update. + * @param int $post_id ID of the post to update. * @param array $fields Post data. * - * @return int|WP_Error The value 0 or WP_Error on failure. The post ID on success. + * @return int|WP_Error The post ID on success. The value 0 or WP_Error on failure. */ public function update_object( $post_id, $fields ) { $fields['ID'] = $post_id; @@ -48,11 +48,11 @@ class WP_UnitTest_Factory_For_Post extends WP_UnitTest_Factory_For_Thing { } /** - * Retrieves a object by an id. + * Retrieves a post by a given ID. * - * @param int $post_id The post id to update. + * @param int $post_id ID of the post to retrieve. * - * @return null|WP_Post WP_Post on success or null on failure. + * @return WP_Post|null WP_Post object on success, null on failure. */ public function get_object_by_id( $post_id ) { return get_post( $post_id ); diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php index 06340c852b..ca331f18d4 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php @@ -46,7 +46,7 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { * @param int|object $term The term to update. * @param array|string $fields The context in which to relate the term to the object. * - * @return int The term id. + * @return int The term ID. */ public function update_object( $term, $fields ) { $fields = array_merge( array( 'taxonomy' => $this->taxonomy ), $fields ); @@ -58,9 +58,9 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { } /** - * Attach terms on the given post. + * Attach terms to the given post. * - * @param int $post_id The Post ID. + * @param int $post_id The post ID. * @param string|array $terms An array of terms to set for the post, or a string of terms * separated by commas. Hierarchical taxonomies must always pass IDs rather * than names so that children with the same names but different parents @@ -76,12 +76,12 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { } /** - * Create a term and returns it as a object. + * Create a term and returns it as an object. * * @param array $args Array or string of arguments for inserting a term. * @param null $generation_definitions The default values. * - * @return null|WP_Error|WP_Term WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure. + * @return WP_Term|WP_Error|null WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure. */ public function create_and_get( $args = array(), $generation_definitions = null ) { $term_id = $this->create( $args, $generation_definitions ); @@ -95,11 +95,11 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing { } /** - * Retrieves the term by given term id. + * Retrieves the term by a given ID. * - * @param int $term_id The term id to retrieve. + * @param int $term_id ID of the term to retrieve. * - * @return null|WP_Error|WP_Term WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure. + * @return WP_Term|WP_Error|null WP_Term on success. WP_error if taxonomy does not exist. Null for miscellaneous failure. */ public function get_object_by_id( $term_id ) { return get_term( $term_id, $this->taxonomy ); diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php index 0fa45059d4..d996213f45 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-thing.php @@ -33,7 +33,7 @@ abstract class WP_UnitTest_Factory_For_Thing { /** * Updates an existing object. * - * @param int $object The object id. + * @param int $object The object ID. * @param array $fields The values to update. * * @return mixed The result. Can be anything. @@ -90,7 +90,7 @@ abstract class WP_UnitTest_Factory_For_Thing { /** * Retrieves an object by ID. * - * @param int $object_id The object id. + * @param int $object_id The object ID. * * @return mixed The object. Can be anything. */ @@ -114,7 +114,7 @@ abstract class WP_UnitTest_Factory_For_Thing { } /** - * Combines the given argument with the generation_definitions (defaults) and applies + * Combines the given arguments with the generation_definitions (defaults) and applies * possibly set callbacks on it. * * @param array $args Optional. The arguments to combine with defaults. Default is empty array. diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php index 3a22ba08d7..966eed8021 100644 --- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php +++ b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php @@ -26,7 +26,7 @@ class WP_UnitTest_Factory_For_User extends WP_UnitTest_Factory_For_Thing { * * @param array $args The user data to insert. * - * @return int|WP_Error + * @return int|WP_Error The user ID on success, WP_Error object on failure. */ public function create_object( $args ) { return wp_insert_user( $args ); @@ -35,10 +35,10 @@ class WP_UnitTest_Factory_For_User extends WP_UnitTest_Factory_For_Thing { /** * Updates the user data. * - * @param int $user_id The user id to update. + * @param int $user_id ID of the user to update. * @param array $fields The user data to update. * - * @return int|WP_Error User id on success. WP_Error on failure. + * @return int|WP_Error The user ID on success, WP_Error object on failure. */ public function update_object( $user_id, $fields ) { $fields['ID'] = $user_id; @@ -46,11 +46,11 @@ class WP_UnitTest_Factory_For_User extends WP_UnitTest_Factory_For_Thing { } /** - * Retrieves the user for given user id. + * Retrieves the user for a given ID. * - * @param int $user_id The user id to get. + * @param int $user_id ID of the user ID to retrieve. * - * @return WP_User The user. + * @return WP_User The user object. */ public function get_object_by_id( $user_id ) { return new WP_User( $user_id );