Handling "since" annotations for re-exports
Currently, users often document the package version in which a declaration was introduced via @since
annotations in their Haddocks. For instance,
module Foo where
-- | Frobbles a foo.
--
-- @since 1.2.3.4
frobbulate :: Foo -> FrobbledFoo
Beyond the usual issues with encoding useful information in unstructured text, this mechanism has the flaw that it deals with re-exports very poorly. Specifically, the "since" information is attached to the declaration itself; there is no way to indicate that a new export of an existing declaration was made available, e.g.:
module Wombat (frobbulate) where
import Foo (frobbulate)
One can think of a few ways to address this:
- Allow documentation on re-exports, as we now do for deprecations. For instance, one might imagine:
module Wombat ( frobbulate -- ^ @since 1.5 ) where ...
- Introduce a more expressive (likely less Haddock-centric) means of encoding this information; For instance,
module Foo where {-# SINCE frobbulate 1.2.3.4 #-} frobbulate :: Foo -> FrobbledFoo module Wombat ( frobbulate {-# SINCE 1.5 #-} ) where ...