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

Reply via email to