[OT] Punctuation of "Params:" and "Returns:"

[Mike Parker via Digitalmars-d]

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:

This one. If nothing were ever to follow the fragment, I would go 
with no caps and no punctuation. As that's not the case, then 
this is the one. It's acceptable in English writing to break the 
rules where it flows and improves readability than to force 
something awkward out of conformity.

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