Re: Proposal: require Haddock comment for every new top-level function and type in GHC source code

Yes, Phabricator/arcanist is probably the best way to do it, I agree. I was more wondering technically how we'd enforce it (just regex? parse/lex the code for top level definitions? etc). There are also other opportunities for linting here, so we should think about that a bit. Anyway, good stuff! On Wed, Jul 2, 2014 at 11:33 AM, Johan Tibell wrote:

On Wed, Jul 2, 2014 at 6:04 PM, Austin Seipp wrote:

...

Of course, I'd also like it if this rule explicitly extended to top-level data types, type classes, etc as well. I believe that was the intention but I'm just making sure. :)

That was the intention.

...

(Finally, I actually would like some kind of mechanical enforcement of this, but I don't think it has to be a hard rule - we shouldn't reject things on that basis alone. I'm not sure how we would do that anyway, though.)

The way I suggest we do this, if we do this, is to add a linter to Phabricator that adds a note to the code review that the new code lacks the appropriate docs. That way we encourage users to add them, without e.g. making validate fail or something similar. This is what we do at Google (and FB too I presume).

-- Regards, Austin Seipp, Haskell Consultant Well-Typed LLP, http://www.well-typed.com/