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
