Package-qualified @since annotations
From @bgamari:
Currently the
@since
annotation is used to communicate the version in which a declaration was introduced in a package. However, there is currently no story for the introduction of declarations by re-exports. For instance, imagine that we have:-- in package foo module Foo (hello) where -- | @since 0.1 hello :: IO () ... -- in package bar module Bar (hello) where import Foo (hello)
The documentation of
Bar
will claim thatBar.hello
has been available since 0.1; however, this is a version of packagefoo
, notbar
.In cases where
foo
andbar
are maintained together, it may make sense to be able to record the availability ofhello
frombar
in the documentation ofFoo
. For instance, you might want to write:-- in package foo module Foo (hello) where -- | -- @since foo-0.1 -- @since bar-0.2 hello :: IO () ...
Clearly this isn't suitable in all cases; encoding information about the exports of one package (
bar
) in another (foo
) is certainly not ideal. However, it is quite useful in cases where an declarations of a internal package are re-exported by a user-facing package.approach does have the advantage of being a simple and easily implemented generalization of the existing mechanism.
Another more general, yet harder to realize, approach can be found in #24836 (closed).