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

On Thu, Sep 22, 2016 at 02:26:15PM -0400, Andrei Alexandrescu via Digitalmars-d 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.
[...]

I personally prefer this version. I don't think it's incorrect. (Even if it is, does it really matter? The intended meaning is clear, and formatting it as a full sentence looks better.)


T

-- 
If you want to solve a problem, you need to address its root cause, not just its symptoms. Otherwise it's like treating cancer with Tylenol...

On Thursday, 22 September 2016 at 18:27:01 UTC, H. S. Teoh wrote:
> On Thu, Sep 22, 2016 at 02:26:15PM -0400, Andrei Alexandrescu via Digitalmars-d wrote: [...]
>> ====
>> Parameters:
>> r | The range subject to partitioning.
>> 
>> Returns:
>> Something awesome.
>> ====
> I personally prefer this version. I don't think it's incorrect. (Even if it is, does it really matter? The intended meaning is clear, and formatting it as a full sentence looks better.)

Me too.

On 09/22/2016 11:26 AM, Andrei Alexandrescu wrote:

> 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.

I agree that only a sentence should have a period.

Although I'm not aware of intra-paragraph dividers in typography, how about using a bullet or a dash before the subsequent sentences:

====
Parameters:
r | the range subject to partitioning • For whatever reason there's a
need for a second sentence, it can follow the divider character. We can
have even more sentences.

While on topic, how about using different colors for template and function parameters? I leave the choice of colors to people with synesthesia. :)

Ali

Am Thu, 22 Sep 2016 14:26:15 -0400
schrieb Andrei Alexandrescu <SeeWebsiteForEmail@erdani.org>:

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

You are not the only one scratching his head. I went through the same stages, from full sentence over removing repeated words, to lowercase without punctuation. /Currently/ I'm using:

  Returns:
    pointer to the parent object; maybe `null` if this is the
    root object

Anything needing a long explanation then needs to be written in a way that it refers to the description paragraph(s) above in brief. Happy bike-shedding :)

-- 
Marco

On Thursday, September 22, 2016 14:26:15 Andrei Alexandrescu via Digitalmars-d 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.

This is what I do (and have done in Phobos). No, it's technically not the best English, but it works quite well IMHO, and almost no one is going to care that it's not perfect English.

- Jonathan M Davis

On Thursday, 22 September 2016 at 22:44:13 UTC, Jonathan M Davis wrote:

> This is what I do (and have done in Phobos). No, it's technically not the best English, but it works quite well IMHO, and almost no one is going to care that it's not perfect English.
>
> - Jonathan M Davis

If we're worried about perfect English, we'll be using complete sentences rather than sentence fragments, so the punctuation won't be relevant.

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:

This one. If nothing were ever to follow the fragment, I would go with no caps and no punctuation. As that's not the case, then this is the one. It's acceptable in English writing to break the rules where it flows and improves readability than to force something awkward out of conformity.

On a related note, I recommend anyone who frequently writes (no matter the context -- software docs included) to read Steven Pinker's 'The Sense of Style' [1]. It's practical advice for modern writing that, IMO, does more to destroy Strunk & White (in a respectful manner) than improve upon it. Basically, he dispenses with dogma in favor of practicality.

[1] http://stevenpinker.com/publications/sense-style-thinking-persons-guide-writing-21st-century

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

On Thursday, 22 September 2016 at 18:26:15 UTC, Andrei Alexandrescu wrote:
> We need to zero in on one good style and use it throughout.

Why?

Shouldn't the main focus be intelligibility rather than being grammatically correct? I really don't think there should be a hard and fast rule for something this trivial when there are a lot of function docs that still don't have these sections in them.