Fix comment casing in yaml documentation

Description

Some comments start with lower case and some with upper e.g.

vs

We should standardize comment casing. This could probably be automated for existing yaml docs.

Environment

None

Pull Requests

None

Activity

Show:

Sandeep Tamhankar April 24, 2017 at 5:25 PM

Totally agree; How about this:

  • Module, class and method descriptions start with upper-case because often times those descriptions contain multiple sentences.

  • Return type descriptions start with lower-case so that trivial functions that return some attribute of an object would say "Returns a foo" in the method description and "a foo" in the `@return`.

  • Param type descriptions should be consistent with return-type since parameters are the "input" while return-type is "output"; they're siblings and should be consistent.

  • Constant and class field descriptions' case should be consistent with one another. I don't feel strongly about which case is best here.

Details

Assignee

Reporter

Priority

Created April 24, 2017 at 12:47 PM
Updated April 24, 2017 at 7:54 PM