From 626f78750bb39fa3b11779b8348045e71d106b0a Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Fri, 30 Jun 2017 04:35:39 +0000
Subject: [PATCH] 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
---
 .../factory/class-wp-unittest-factory-for-blog.php   | 10 ++++++++++
 .../class-wp-unittest-factory-for-bookmark.php       |  7 +++++++
 .../class-wp-unittest-factory-for-comment.php        | 10 ++++++++++
 .../class-wp-unittest-factory-for-network.php        | 10 ++++++++++
 .../factory/class-wp-unittest-factory-for-post.php   | 10 ++++++++++
 .../factory/class-wp-unittest-factory-for-term.php   | 12 ++++++++++++
 .../factory/class-wp-unittest-factory-for-user.php   | 10 ++++++++++
 7 files changed, 69 insertions(+)

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 795f09f8b7..a62bbdd828 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
@@ -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 ) {
diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-bookmark.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-bookmark.php
index cd472271ba..6c288e0ba1 100644
--- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-bookmark.php
+++ b/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 {
 
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 cd853cc863..23580dd8bc 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
@@ -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 ) {
diff --git a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-network.php b/tests/phpunit/includes/factory/class-wp-unittest-factory-for-network.php
index 801610ac43..ae29ca929e 100644
--- a/tests/phpunit/includes/factory/class-wp-unittest-factory-for-network.php
+++ b/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 ) {
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 1ab7d4bc44..7203015d3d 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
@@ -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 ) {
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 1b6f342e2c..6435b193b5 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
@@ -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;
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 4c1151a8a5..1140e26153 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
@@ -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 ) {