[haddock] #97: Reusable named chunks of documentation for declarations

[haddock]

#97: Reusable named chunks of documentation for declarations
------------------------+---------------------------------------------------
Reporter:  Deewiant     |       Owner:       
    Type:  enhancement  |      Status:  new  
Priority:  major        |   Milestone:  2.5.0
 Version:  2.4.1        |    Keywords:       
------------------------+---------------------------------------------------
 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.

-- 
Ticket URL: <http://trac.haskell.org/haddock/ticket/97>
haddock <http://www.haskell.org/haddock>
Haddock, The Haskell Documentation Tool