Package-qualified @since annotations #1630
Description
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 that Bar.hello has been available since 0.1; however, this is a version of package foo, not bar.
In cases where foo and bar are maintained together, it may make sense to be able to record the availability of hello from bar in the documentation of Foo. 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 #1629.