[OT] Punctuation of "Params:" and "Returns:"
Claude via Digitalmars-d
digitalmars-d at puremagic.com
Fri Sep 23 05:02:10 PDT 2016
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)
More information about the Digitalmars-d
mailing list