Reusable named chunks of documentation for declarations

[ghc-mirror]

Original reporter: matti.niemenmaa+haddockbugs@

Currently there is no way of using the same piece of Haddock documentation for two different declarations, apart from copying and pasting it, which can easily lead to them falling out of sync. The current -- $ syntax only works for documentation which is not attached to declarations.

Support for this is useful in cases where you have two or more functions which essentially implement a common interface that hasn't been made into a type class. Examples are Data.ByteString versus Data.ByteString.Lazy or Data.Map versus Data.IntMap: looking at the docs of bytestring-0.9.1.4 I see that Data.ByteString.Lazy.intersperse doesn't say that it's O(n), but Data.ByteString.intersperse does—an obvious omission. There should be a mechanism for avoiding these kinds of errors, which tend to become worse over time.

Extending the -- $ syntax makes the most sense to me. It could be possible to write something like the following, taking append from bytestring as an example:

module Data.ByteString (...) where
...

-- | @O(n)@ $append
...

module Data.ByteString.Lazy (...) where
...

-- | @O(n/c)@ $append
...

-- $append
-- Append two ByteStrings.

One thing that isn't obvious to me: should the definitions of the chunks have to be in the same module, like now, thus essentially forcing CPP usage? Or would an import be okay? That could lead to ambiguity—should the normal Haskell disambiguation syntax (Module.foo) be allowed, then? That could make this ridiculously complex; CPP seems the simplest solution but it's arguably not very clean. Either way would satisfy me.

[ntc2]

Issue #179 is related.

[chshersh]

I'm interested in this issue as well. I have data type with huge chunks of documentation for every constructor. It would be much nicer, if I could write the documentation separately to make code cleaner.

• https://github.com/kowainik/tomland/blob/b098ac6091e317268e760b40e0b974ba11649d8d/src/Toml/Type/Value.hs#L41-L136

[evincarofautumn]

“I have data type with huge chunks of documentation for every constructor. It would be much nicer, if I could write the documentation separately to make code cleaner.” — @chshersh

I often have the same use case. What I’d like to be able to write is something like this:

data Expr … where
  EUnit    :: {}            -> Expr …  -- ^ $expr_unit
  EVar     :: …             -> Expr …  -- ^ $expr_var
  ELiteral :: …             -> Expr …  -- ^ $expr_literal
  EList    :: …             -> Expr …  -- ^ $expr_list
  ELet     :: … -> … -> …   -> Expr …  -- ^ $expr_let
  EApply   :: … -> …        -> Expr …  -- ^ $expr_apply
  EMatch   :: … -> …        -> Expr …  -- ^ $expr_match
  …  

-- $expr_unit
--
-- …
--

-- $expr_var
-- 
-- …
--

-- $expr_literal
--
-- …
--

…

Or, I’d be happy with whatever lets me accomplish my actual goal: to attach documentation to something by name, out of line, so that I can both see the code at a glance, and easily copy the list of constructors to make an exhaustive case on the data type.

For instance, something like Doxygen’s structural commands @class (a.k.a. @struct), @var (a.k.a. @fn, @typedef, or @property), and so on. For Haddock, these could all be spelled @about, unless there’s a particular reason for them to be distinguished.

data Expr … where
  EUnit    :: {}            -> Expr …
  EVar     :: …             -> Expr …
  ELiteral :: …             -> Expr …
  EList    :: …             -> Expr …
  ELet     :: … -> … -> …   -> Expr …
  EApply   :: … -> …        -> Expr …
  EMatch   :: … -> …        -> Expr …
  …  

-- | @about EUnit
--
-- …
--

-- | @about EVar
--
-- …
--

-- | @about ELiteral
--
-- …
--

…

-- | … would ordinarily apply to the subsequent definition, but -- | @about name would instead attach it to name.

I am a bit loath to suggest adding more notation, especially with @. Poor Haddock’s markup could really use some thoughtful design love, one of these days! There is precedent for this kind of thing with @since, it’s just not backward-compatible with @…@ code formatting.