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

[Austin Seipp]

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 <johan.tibell at gmail.com> wrote:
> On Wed, Jul 2, 2014 at 6:04 PM, Austin Seipp <austin at well-typed.com> 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/