On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton Jones <simo...@microsoft.com> wrote: > I’d be OK with this, (it’s a bit like requiring signatures on all top level > functions) but I don’t know how we’d enforce it.
I think social enforcement is enough. If we agree that this is something we want to do and communicate that to ghc-devs@, put a note in our style guide, and kindly remind people to add comments when we do code reviews, we'll eventually end up with a culture of writing Haddocks. I think the most important part right now is that current contributors agree that this is something we want to do. Aside: people usually say that they find it hard to know what to document in their own code, because they don't know what others will find difficult. My advice is this: add a sentence or two about what the function does and why it exists, no matter how obvious you think that statement is. > Do you think the requirement should be for all top-level functions or just > exported ones? I take what I can get, but I think documenting all top-level functions makes sense in the case of GHC, as there's so much that goes on in our modules but we often only export a handful of functions. For example, compiler/codeGen/StgCmmPrim.hs is 2,000 lines long but only exports 3 functions. For someone that wants to work on that module for the first time only have docs on those three functions is helpful, but likely not enough. FWIW I document all top-level functions in my projects (and when I don't I often regret it later). > I agree that Notes have a different purpose. But it should be OK style to > refer to a Note from a top-level function comment, even though Haddock won’t > be able to make much sense of it. Sure. Personally I would refer to the note from the function body if it talks mostly about the implementation, as opposed to how to use the function. -- Johan _______________________________________________ ghc-devs mailing list ghc-devs@haskell.org http://www.haskell.org/mailman/listinfo/ghc-devs
