Skip to content

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 ...
    This, however, introduces thorny questions of what it means for a declaration to have more than one docstring. It's not clear to me that we want to address this question.
  • 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 ...
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information