Haddock paragraph whitespace about guides

[jdreaver]

Ah I thought Title meant Summary. If we are being explicit then Summary seems like the right word/style.

[tfausak]

Just jumping in to say that option A reminds me of Python's docstring conventions:

Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.

So there's precedent for such a guideline 🙂

[cdparks]

I used to do B, but @pbrisbin brainwashed me, so I've been doing A. I don't really prefer one or the other, but if A's already got the numbers, cool. Hard 👍 on Summary + Body, just like commit messages

[eborden]

[pbrisbin]

/cc @cdparks @eborden @5outh @jdreaver @rogers89

[jdreaver]

I'm 👍 with the space rules in option A but, does this mean we must have a title line? What about this:

-- | This is a haddocks comment that I am making up for the purpose of demonstration
-- and it is kinda long. Not too long though, since it is just two sentences.
--
foo :: Int
foo = 1

Obviously a rule of thumb for writing in general is to break up long paragraphs, but certainly this paragraph is not too long. I'm all for option A, but if option A enforces having a title then I think I'm 👎

(Note: option A doesn't talk about the Title, option D does, which is why I got this impression):

Haddocks are better with a distinct Title and Body.

[pbrisbin]

Your example would not be allowed, IMO. What you describe is an omitted mix-match of (D) and (A).

Some other rules I plan to propose are:

• Haddocks must have a Summary and optional Body
• Summaries have some rules that are inspired by good commit messages, in this case it must be a single, short, and un-punctuated statement

Only if there is a Body, do the rules in this Issue apply.

So your example would either be:

-- | Something like this
foo :: Int

if it truly is sufficiently simple. Otherwise, you have to jump to

-- | Something shorter
--
-- With whatever you were planning above being here instead. This is a haddocks
-- comment that I am making up for the purpose of demonstration and it is kinda
-- long. Not too long though, since it is just two sentences.
--
foo :: Int
foo = 1

I know you probably want the freedom to go with "but it's just two sentences", but:

• Not enforcing this really damages the goal of consistency and scannability
• Enforcing this will foster more documentation, because once you've made the jump from a Summary to a Summary+Body, you are naturally willing to write more in the Body -- this how it works in commit messages

To recap:

1. Option (A) does not enforce that there is a Body
2. Other rules would add restrictions on Summary length and formatting
3. If what you want to write can't fit in (2), you should have a Body

If (2) is controversial, maybe we can open a separate Issue and elicit a separate discussion?

Edited to say "Summary", not "Title"

[eborden]

I have no skin in this game. You seem passionate about the first option, so I'm down for it.

[jdreaver]

Yeah it reminds me of Python too. I can get onboard with a title + body. I tend to do title + body anyway for much longer Haddock comments, so stomping out the inconsistency for shorter ones should be fine.

[pbrisbin]

I guess now's the time to decide then:

• Title + Body (what I did here, for some reason?)
• Summary + Body (python, git commits)
• Subject + Body (email)

Edit: Summary won.

[tfausak]

For what it's worth, I like option B. The extra blank line before the type signature looks weird to me. But not weird enough that I would actually fight it. And to continue cribbing from Python, every docstring ends with that triple quote on its own line.

[pbrisbin]

Done. Edited existing stuff to use "Summary" consistently.

[5outh]

I'm 👍 on A!

[pbrisbin]

Closing this issue. My PR will include (A) as well as the other rules hinted at in this thread.

Don't let it being closed stop the GIFs though.

[tfausak]