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
