[wp-trac] [WordPress Trac] #35494: Add inline docs for unit test suite
WordPress Trac
noreply at wordpress.org
Tue Feb 23 17:57:29 UTC 2016
#35494: Add inline docs for unit test suite
------------------------------+-------------------
Reporter: ericlewis | Owner:
Type: defect (bug) | Status: new
Priority: normal | Milestone: 4.5
Component: Build/Test Tools | Version:
Severity: normal | Resolution:
Keywords: has-patch | Focuses: docs
------------------------------+-------------------
Comment (by DrewAPicture):
Replying to [comment:9 ericlewis]:
> Replying to [comment:8 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:
[[Image(http://f.cl.ly/items/2Q2D3O170U1g2X141J23/Screen%20Shot%202016-02-23%20at%2010.52.29%20AM.png)]]
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 :-)
--
Ticket URL: <https://core.trac.wordpress.org/ticket/35494#comment:10>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform
More information about the wp-trac
mailing list