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

[Andrei Alexandrescu via Digitalmars-d]

Consider e.g. 
http://dtest.thecybershadow.net/artifact/website-ff971425e306789aa308cfb07cba092cadd11161-d41523308b293d6e0a3d6da971a68db8/web/phobos-prerelease/std_algorithm_sorting.html#pivotPartition, 
where we can see the parameters table and the returns subsection.

How to formulate these lingustically? If we try do do that with full 
grammatical sentences, it's awkward:

====
Parameters:
r | r is the range subject to partitioning.

Returns:
Returns something awesome.
====

So attempting to use full sentences with subject and predicate leads to 
repetition of the parameter name and of the "Returns" word. Which is 
silly. Next attempt is to use sentence fragments, but format as sentences:

====
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:

====
Parameters:
r | the range subject to partitioning

Returns:
something awesome
====

So now we don't use a leading capital and punctuation. The challenge 
here is when the parameter description takes more than one sentence:

====
Parameters:
r | the range subject to partitioning. For whatever reason there's a 
need for a second sentence, so we need to put a period and mess it all up.

Returns:
something awesome. Sadly, it takes one extra sentence too, making the 
"something awesome" text awkward.
====

We need to zero in on one good style and use it throughout. Thoughts?


Andrei