[wp-trac] [WordPress Trac] #35494: Add inline docs for unit test suite

[WordPress Trac]

#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