id,summary,reporter,owner,description,type,status,priority,milestone,version,resolution,keywords,cc
97,Reusable named chunks of documentation for declarations,Deewiant,,"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.",enhancement,new,major,,2.4.1,,,