META-PROPOSAL: Documentation should be required to say when exports were introduced

[Henning Thielemann]

On Sat, 17 Nov 2007, Ian Lynagh wrote:

> This is trac #1903:
>     http://hackage.haskell.org/trac/ghc/ticket/1903
>
> One of the nice things about, for example, PHP is that if you look at
> the documentation for one of its functions, e.g.
>     http://www.php.net/manual/en/function.file-get-contents.php
> it tells you that file_get_contents is available in PHP >= 4.3.0.
>
> I propose that all exports in Haskell libraries should be required to
> have such a thing in their haddock documentation. For the current code
> we could either give the current versions as the date of introduction,
> or do some digging and put precise data in.

It should be automated, otherwise it will be a new source of
misdocumentation. There should be a tool that determines the earliest
occurence of a function given a list of package directories or a darcs
repository. This tool could generate a file with the information of when
functions were introduced. The file could also be managed incrementally.
That is, whenever 'Setup.hs dist' is run, then new function names plus the
current .cabal version are added to the function versioning file. This
file must be understood by Haddock. Hackage could use this tool to
automatically add the information in the online documentation.