@since annotations on exports

[bgamari]

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.

[chreekat]

The need for "odd syntax" gives me a lot of pause, and I think we should take more than just a few days' time thought before moving ahead with it. But I do think we annotating re-exports should somehow be possible.

Does this have to happen before the ghc-internals split happens?

[bgamari]

Does this have to happen before the ghc-internals split happens?

We need to do something, otherwise we will regress the documentation of base. However, IMHO #1630 seems like an easy, unobjectionable generalization which will address our needs without saddling us with potentially undesirable syntactic decisions in the future.

[int-index]

The proposed syntax looks perfectly fine to me. I can immediately understand what it means in this example, and it's also the first thing I would've tried myself if I wanted to annotate an exported entity.

Indeed there's a bit of friction with the semantics of -- | comments, but we have to make do with the remaining syntactic space afforded to us. I doubt anyone will come up with a more intuitive syntax anyway.

[Bodigrim]

FWIW I'm also fine with the proposed syntax.

[chreekat]

The syntax here is somewhat odd: @sincecomments 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.

I guess the original oddity is that -- | already does something that -- ^ doesn't do. Does -- ^ do anything at all currently in export lists? Is it a syntax error? How will Haskell formatters handle it?

[bgamari]

Currently -- ^ comments are ignored in export lists.