Make WordPress Core

Opened 9 years ago

Closed 9 years ago

Last modified 9 years ago

#35494 closed defect (bug) (fixed)

Add inline docs for unit test suite

Reported by: ericlewis's profile ericlewis Owned by: ericlewis's profile ericlewis
Milestone: 4.5 Priority: normal
Severity: normal Version:
Component: Build/Test Tools Keywords:
Focuses: docs Cc:

Description


Attachments (2)

35494.diff (1.6 KB) - added by ericlewis 9 years ago.
35494.2.diff (1.7 KB) - added by boonebgorges 9 years ago.

Download all attachments as: .zip

Change History (15)

@ericlewis
9 years ago

#1 @ericlewis
9 years ago

  • Keywords has-patch added

#2 @ericlewis
9 years ago

  • Milestone changed from Awaiting Review to 4.5

#3 @jdgrimes
9 years ago

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.

#4 @swissspidy
9 years ago

  • Component changed from General to Build/Test Tools

@boonebgorges
9 years ago

#5 follow-up: @boonebgorges
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 @ericlewis
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?

#8 follow-up: @DrewAPicture
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: @ericlewis
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 @DrewAPicture
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:
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 :-)

This ticket was mentioned in Slack in #core by eric. View the logs.


9 years ago

#12 @ericlewis
9 years ago

  • Owner set to ericlewis
  • Resolution set to fixed
  • Status changed from new to closed

In 36854:

Build/Test Tools: Document PHP unit test classes.

Props boonebgorges.
Fixes #35494.

#13 @ericlewis
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.

Note: See TracTickets for help on using tickets.