[Haddock] [haddock] #185: Allow attaching new docs to functions that are re-exported

[haddock]

#185: Allow attaching new docs to functions that are re-exported
------------------------+---------------------------------------------------
Reporter:  duncan       |       Owner:        
    Type:  enhancement  |      Status:  new   
Priority:  major        |   Milestone:  2.10.0
 Version:  2.9.2        |    Keywords:        
------------------------+---------------------------------------------------
 Use case:

 We have `Data.Monoid` which exports `(<>)` with its associated
 documentation. We have a number of other modules that re-export the `(<>)`
 operator, such as `Text.Pretty`. These modules want to provide their own
 documentation for the `(<>)` operator.

 Historically `Text.Pretty` defined `(<>)` locally so it was possible for
 it to give it documentation that makes sense in the context of
 `Text.Pretty`. Now that we have the `(<>)` defined in `Data.Monoid` and
 re-exported, that's no longer possible. Note that we do not want to define
 `(<>)` locally anymore, we really do want to re-export `Data.Monoid.<>`,
 we just want to give it more context sensitive documentation.

 Note that this would be useful in other cases where some highly generic
 function is re-exported by a module dealing with a specific type. For
 example, suppose we changed `Data.List` to re-export
 `Data.Foldable.foldr`. We would not want to change the documentation of
 `foldr` in `Data.List`.

 So how might this work?

 The only place we could attach documentation would be in the export list,
 since that's the only place where we mention the function. So perhaps
 something like:

 {{{
 module Text.PrettyPrint.HughesPJ (
   ...
   -- ** Combining documents
   empty,
   -- | Beside.
   -- '<>' is associative, with identity 'empty'.
   (<>),
   (<+>), hcat, hsep,
   ...
 )  where

 import Data.Monoid ( Monoid(mempty, mappend), (<>) )

 }}}

 Presumably it also makes sense to allow $named doc chunks there too? I've
 never been quite sure of the syntax for that so I'm not sure if it'd add
 ambiguity.

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