haddock icon indicating copy to clipboard operation
haddock copied to clipboard

`@since` annotations on exports

Open bgamari opened this issue 1 year ago • 6 comments

It should be possible to annotate re-exported declarations with @since annotations. For instance, imagine we have a module Foo. In version 0.2 of the package providing Foo we might decide we want to re-export Bar.bat from Foo. In order to communicate this change to the user we would want to write something like:

module Foo
    ( bat -- ^ @since 0.2
    ) where

import Bar (bat)

Ideally Foo's documentation would then reproduce the documentation of Foo but with the @since annotation saying something like Since: 0.2 (exported from 'Bar').

The syntax here is somewhat odd: @since comments in export lists must be expressed as -- ^ docstrings as the usual -- | syntax in an export list is already used to express a docstring comment detached from any declaration.

bgamari avatar Feb 04 '24 00:02 bgamari