On Thursday, 22 September 2016 at 18:26:15 UTC, Andrei Alexandrescu wrote:
> Parameters:
> r | The range subject to partitioning.
>
> Returns:
> Something awesome.
> ====
>
> This is incorrect because one is not supposed to punctuate sentence fragments as full sentences. Next attempt:

I also prefer that version.

And I think it makes sense even linguistically.

Sentences in english could be formalized as:
<Subject> <verb> <object> [when/where/why/...].

But sometimes, only fragments of sentences are used, when a fragment is already implied.
For instance, for the imperative form, we may write

  Alice said to Bob: "Do this!".

"Do this!" is a perfectly valid english sentence, and the subject is implied: Bob (and not Alice). Expanded, it would give:

  Alice wants Bob to do this.
Or:
  Alice wants "Bob does this".


So, for comments, it is also ok to do the same.

i.e.

/**
 * Get a coefficient from the 2D matrix. (subject implied: function getCoef)
 *
 * Parameters:
 *   r | Row index. (subject implied: parameter r)
 *   c | Column index. (subject implied: parameter c)
 *
 * Returns:
 *   Coefficient fetched at the specified row and column. (subject implied: Return value)
 */
float getCoef(int r, int c)

On 9/23/16 2:17 AM, Mike Parker wrote:
>
> On a related note, I recommend anyone who frequently writes (no matter
> the context -- software docs included) to read Steven Pinker's 'The
> Sense of Style' [1]. It's practical advice for modern writing that, IMO,
> does more to destroy Strunk & White (in a respectful manner) than
> improve upon it. Basically, he dispenses with dogma in favor of
> practicality.
>
> [1]
> http://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century

Thanks for the book reco, looks great. -- Andrei