Add inline docs for unit test suite

[jdgrimes]

It would be helpful if @method docs were added for each of the factories' create(), create_and_get(), and create_many() methods. Because these methods are defined only once in the Factory_For_Thing class, the precise return values of each one is not documented for each factory. I've found that adding @method docs to each factory so that the return types are documented is very helpful, especially when using an IDE with auto-completion. That way you know that you are getting a WP_User object when you call $this->factory->user->create_and_get(), for example.

[boonebgorges]

35494.2.diff​ is a friendly amendment of formatting/wording. (Method/function short descriptions can be up to 120 chars, and should never contain line breaks.)

[ericlewis]

Replying to boonebgorges:

35494.2.diff​ is a friendly amendment of formatting/wording. (Method/function short descriptions can be up to 120 chars, and should never contain line breaks.)

Thanks! Do long descriptions have the same line break guidelines?

[boonebgorges]

I think so, but I defer to @DrewAPicture. (Both ​https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md and ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/ are silent on this point.)

[DrewAPicture]

Method descriptions, referred to as "summaries" in the standard, can wrap to up to an optional (though unusual) second line. We typically wrap lines at 80-120 characters depending on how far the gutter is indented.

In the class DocBlock for WP_UnitTestCase, I see no reason for the extra blank lines, but it doesn't hurt anything to leave them.

[ericlewis]

Replying to DrewAPicture:

Method descriptions, referred to as "summaries" in the standard, can wrap to up to an optional (though unusual) second line. We typically wrap lines at 80-120 characters depending on how far the gutter is indented.

Cool — is there a rule of thumb we can use to decide where between 80 and 120 we should wrap?

In the class DocBlock for WP_UnitTestCase, I see no reason for the extra blank lines, but it doesn't hurt anything to leave them.

You mean in the long description, right? Should long descriptions typically not have double line breaks between lines?

[DrewAPicture]

Replying to ericlewis:

Replying to DrewAPicture:

Method descriptions, referred to as "summaries" in the standard, can wrap to up to an optional (though unusual) second line. We typically wrap lines at 80-120 characters depending on how far the gutter is indented.

Cool — is there a rule of thumb we can use to decide where between 80 and 120 we should wrap?

Again, it's about where the gutter is indented. In the case of a hash notation, the 120-character mark often serves as the designated wrap point because the descriptions tend to be already indented themselves. In my editor I have the guide-line set at 120 characters, and as you can see that's used pretty consistently:

Think of it this way: The actual line should span approximately 80 characters and fall within a 120 character span. It's entirely about readability and has no bearing on the tests themselves.

In the class DocBlock for WP_UnitTestCase, I see no reason for the extra blank lines, but it doesn't hurt anything to leave them.

You mean in the long description, right? Should long descriptions typically not have double line breaks between lines?

Writing the description is just like writing anything else. If you feel like four sentences need to each stand on their own instead of in a paragraph, that's your prerogative :-)

[ericlewis]

In 36854:

Build/Test Tools: Document PHP unit test classes.

Props boonebgorges.
Fixes #35494.

[ericlewis]

Thanks for the notes @DrewAPicture! I added a ​section to PHP Inline Documentation Standards to describe general practices.