New policy: write valid Haddocks for all new Haskell code

[dhess]

It's time we start writing proper Haddocks for all new Haskell code. I propose that we have a flag day sometime soon and start requiring them for all new code that warrants them.

Also, I propose that we adopt a policy of writing proper Haddocks whenever we make a change to an existing top-level definition, so that over time, we can retroactively add them to existing code.

Any objections?

[georgefst]

Seems reasonable. I've never been in the habit of reaching 100% coverage, due to:

• Functions whose purpose seems obvious from their type:

  -- | Convert an 'A' to a 'B' in the obvious way.
  convertAtoB :: A -> B

• Internal (i.e. non-exported definitions) whose purpose is obvious in context.
• Large groups of similar definitions, where a section header seems more appropriate.

But it is probably worth aiming for. We can always discuss in a PR review if there's a really good reason not to bother haddock-ing something.

[dhess]

Sure, having a "comments required for new code" policy doesn't mean we need to abandon good commenting practice. I think we do a good job on commenting practice already, anyway, and we all occasionally ask each other for additional/clearer comments when we think they're warranted.

The only thing that would change in this new policy is that we should take the time to write the proper Haddock markup, which we currently do very poorly and inconsistently. So here, focus on the "proper Haddocks" bit; no need to change anything else, as far as I'm concerned.

[georgefst]

Ah, okay, I did misinterpret the main purpose of this issue.