Tests: Add `@method` notations to factor class DocBlocks as a way to indicate expected return types from factory methods for the benefit of IDEs.

Props jdgrimes.
Fixes #37867.


git-svn-id: https://develop.svn.wordpress.org/trunk@40968 602fd350-edb4-49c9-b593-d223f7449a82

tests/phpunit/includes/factory/class-wp-unittest-factory-for-blog.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Unit test factory for sites on a multisite network.
+ *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method WP_Site create_and_get( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
+ */
 class WP_UnitTest_Factory_For_Blog extends WP_UnitTest_Factory_For_Thing {
 
 	function __construct( $factory = null ) {

tests/phpunit/includes/factory/class-wp-unittest-factory-for-bookmark.php

@@ -3,7 +3,14 @@
 /**
  * Factory for creating fixtures for the deprecated Links/Bookmarks API.
  *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
  * @since 4.6.0
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method object create_and_get( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
  */
 class WP_UnitTest_Factory_For_Bookmark extends WP_UnitTest_Factory_For_Thing {
 

tests/phpunit/includes/factory/class-wp-unittest-factory-for-comment.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Unit test factory for comments.
+ *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method WP_Comment create_and_get( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
+ */
 class WP_UnitTest_Factory_For_Comment extends WP_UnitTest_Factory_For_Thing {
 
 	function __construct( $factory = null ) {

tests/phpunit/includes/factory/class-wp-unittest-factory-for-network.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Unit test factory for networks.
+ *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method WP_Network create_and_get( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
+ */
 class WP_UnitTest_Factory_For_Network extends WP_UnitTest_Factory_For_Thing {
 
 	function __construct( $factory = null ) {

tests/phpunit/includes/factory/class-wp-unittest-factory-for-post.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Unit test factory for posts.
+ *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method WP_Post create_and_get( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
+ */
 class WP_UnitTest_Factory_For_Post extends WP_UnitTest_Factory_For_Thing {
 
 	function __construct( $factory = null ) {

tests/phpunit/includes/factory/class-wp-unittest-factory-for-term.php

@@ -1,5 +1,14 @@
 <?php
 
+/**
+ * Unit test factory for terms.
+ *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
+ */
 class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing {
 
 	private $taxonomy;
@@ -35,6 +44,9 @@ class WP_UnitTest_Factory_For_Term extends WP_UnitTest_Factory_For_Thing {
 		return wp_set_post_terms( $post_id, $terms, $taxonomy, $append );
 	}
 
+	/**
+	 * @return array|null|WP_Error|WP_Term
+	 */
 	function create_and_get( $args = array(), $generation_definitions = null ) {
 		$term_id = $this->create( $args, $generation_definitions );
 		$taxonomy = isset( $args['taxonomy'] ) ? $args['taxonomy'] : $this->taxonomy;

tests/phpunit/includes/factory/class-wp-unittest-factory-for-user.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Unit test factory for users.
+ *
+ * Note: The below @method notations are defined solely for the benefit of IDEs,
+ * as a way to indicate expected return values from the given factory methods.
+ *
+ * @method int create( $args = array(), $generation_definitions = null )
+ * @method WP_User create_and_get( $args = array(), $generation_definitions = null )
+ * @method int[] create_many( $count, $args = array(), $generation_definitions = null )
+ */
 class WP_UnitTest_Factory_For_User extends WP_UnitTest_Factory_For_Thing {
 
 	function __construct( $factory = null ) {