Allow attaching new docs to functions that are re-exported

[ghc-mirror]

Original reporter: @dcoutts

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.

[ghc-mirror]

Original reporter: @tibbe Isn't this mostly solved by class instance docs?

[ghc-mirror]

Original reporter: david.waern@

Replying to @tibbe:

Isn't this mostly solved by class instance docs?

You can't currently document methods of instances, only instances as wholes.

In any case I think sooner or later you'd want to attach specialized documentation to non-methods.

[andreasabel]

I'd like to attach documentation to a function that is rededicated to a new purpose, in this case lookup. The current issue would give me a natural location where to attach this documentation.

module Agda.Utils.AssocList
  ( module Agda.Utils.AssocList
  , lookup
    -- ^ O(n).
    -- Reexported from 'Data.List'.
  ) where

import Data.List (lookup)

-- | O(n).
--   Get the domain (list of keys) of the finite map.
keys :: AssocList k v -> [k]
keys = map fst
...

Alternative, such a documentation could be added to the import list, like:

import Data.List 
  ( -- | O(n).
    -- Reexported from 'Data.List'.
    lookup
  )