[wp-trac] [WordPress Trac] #37867: Document return types for create/create_and_get/create_many() methods of factory classes

[WordPress Trac]

#37867: Document return types for create/create_and_get/create_many() methods of
factory classes
------------------------------+------------------------------
 Reporter:  jdgrimes          |       Owner:
     Type:  enhancement       |      Status:  new
 Priority:  normal            |   Milestone:  Awaiting Review
Component:  Build/Test Tools  |     Version:  3.7
 Severity:  normal            |  Resolution:
 Keywords:  2nd-opinion       |     Focuses:  docs
------------------------------+------------------------------

Comment (by jdgrimes):

 Replying to [comment:6 boonebgorges]:
 > The PHPDocumentation description for `@method` suggests that it's
 specifically for use in contexts where `__call()` is used on a parent
 class, so that there are no methods where the documentation could
 naturally appear. This isn't the case for `create()` and friends. I'm not
 sure how PhpStorm and similar IDEs handle this sort of thing, but it seems
 like they (or their users) should be able to traverse the inheritance tree
 for this sort of thing.
 https://www.phpdoc.org/docs/latest/references/phpdoc/tags/method.html
 >
 > Now, it so happens that the classes in question - `create_object()`,
 `update_object()`, `create()`, etc on `WP_UnitTest_Factory_For_Thing` - do
 not have any PHPDoc at all. I bet proper documentation of these would be
 enough to make your IDE document the child classes properly.


 Well, the problem isn't that the methods themselves aren't documented, but
 that their return values aren't. Documenting them on the base class would
 require us to use generic values, which wouldn't help. By using the
 `@method` annotation, we're able to specify that calling
 `$factory->user->create_and_get()` will return a `WP_User` object, whereas
 `$factory->site->create_and_get()` will return a `WP_Site`. This is
 helpful fore code autocompletion, and just for documentation purposes in
 general.

 It is true of course that advanced IDEs should theoretically be able to
 figure out this information, but that doesn't help devs who are new to the
 factories to understand exactly what is going on. The `@method`
 annotations provide explicit documentation that is helpful for everyone, I
 think.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/37867#comment:7>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform