www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - [OT] Punctuation of "Params:" and "Returns:"

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Consider e.g. 
http://dtest.thecybershadow.net/artifact/website-ff971425e306789aa308cfb07cba092cadd11161-d41523308b293d6e0a3d6da971a68db8/web/phobos-prerelease/std_algorithm_sorting.
tml#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
Sep 22 2016
next sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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...
Sep 22 2016
parent Sebastiaan Koppe <mail skoppe.eu> writes:
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.
Sep 22 2016
prev sibling next sibling parent =?UTF-8?Q?Ali_=c3=87ehreli?= <acehreli yahoo.com> writes:
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
Sep 22 2016
prev sibling next sibling parent Marco Leise <Marco.Leise gmx.de> writes:
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.
tml#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
Sep 22 2016
prev sibling next sibling parent reply Jonathan M Davis via Digitalmars-d <digitalmars-d puremagic.com> writes:
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
Sep 22 2016
parent bachmeier <no spam.net> writes:
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.
Sep 22 2016
prev sibling next sibling parent reply Mike Parker <aldacron gmail.com> writes:
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
Sep 22 2016
parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 9/23/16 2:17 AM, Mike Parker wrote:

 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


Thanks for the book reco, looks great. -- Andrei
Sep 23 2016
prev sibling next sibling parent Jacob Carlborg <doob me.com> writes:
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
Sep 23 2016
prev sibling next sibling parent Jack Stouffer <jack jackstouffer.com> writes:
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.
Sep 23 2016
prev sibling parent Claude <no no.no> writes:
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)
Sep 23 2016