[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