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

[Jacob Carlborg via Digitalmars-d]

On 2016-09-22 20:26, Andrei Alexandrescu wrote:

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

I use this style.

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

For the parameters I would skip the trailing period. I view the 
parameters as a list and I've learned that the items in a lists (bullet 
point lists) should not end with a period. I might be completely wrong 
and it might not apply to English, but that's what I do.

Keep in mind as well that all this might also depend on how Ddoc renders 
the documentation. For example, if Ddoc renders the returns section like 
this:

Returns: some useful value

Then it make senses to skip the leading capitalization. But if Ddoc 
renders the section like this:

Return Value:
some useful value

Then it might look awkward to not use leading capitalization. Same thing 
with the parameters. It all depends on if the section/parameter is 
rendered in a way that it makes sense/make it look like the 
section/parameter is part of the sentence.

-- 
/Jacob Carlborg