#35494 closed defect (bug) (fixed)
Add inline docs for unit test suite
Reported by: |
|
Owned by: |
|
---|---|---|---|
Milestone: | 4.5 | Priority: | normal |
Severity: | normal | Version: | |
Component: | Build/Test Tools | Keywords: | |
Focuses: | docs | Cc: |
Description
Attachments (2)
Change History (15)
#5
follow-up:
↓ 6
@
9 years ago
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.)
#6
in reply to:
↑ 5
@
9 years ago
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?
#7
@
9 years ago
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.)
#8
follow-up:
↓ 9
@
9 years ago
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.
#9
in reply to:
↑ 8
;
follow-up:
↓ 10
@
9 years ago
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?
#10
in reply to:
↑ 9
@
9 years ago
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 :-)
This ticket was mentioned in Slack in #core by eric. View the logs.
9 years ago
#12
@
9 years ago
- Owner set to ericlewis
- Resolution set to fixed
- Status changed from new to closed
In 36854:
#13
@
9 years ago
- Keywords has-patch removed
Thanks for the notes @DrewAPicture! I added a section to PHP Inline Documentation Standards to describe general practices.
It would be helpful if
@method
docs were added for each of the factories'create()
,create_and_get()
, andcreate_many()
methods. Because these methods are defined only once in theFactory_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 aWP_User
object when you call$this->factory->user->create_and_get()
, for example.