Closed bgamari closed 1 month ago
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?
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.
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.
FWIW I'm also fine with the proposed syntax.
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.
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?
Currently -- ^
comments are ignored in export lists.
Issue has been migrated to https://gitlab.haskell.org/ghc/ghc/-/issues/24836. Thanks all!
It should be possible to annotate re-exported declarations with
@since
annotations. For instance, imagine we have a moduleFoo
. In version0.2
of the package providingFoo
we might decide we want to re-exportBar.bat
fromFoo
. In order to communicate this change to the user we would want to write something like:Ideally
Foo
's documentation would then reproduce the documentation ofFoo
but with the@since
annotation saying something likeSince: 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.