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

[Stefan O'Rear]

On Sat, Nov 17, 2007 at 04:29:45PM +0100, Henning Thielemann wrote:
> 
> 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.

I think some variation of this is a great idea, and its absense has
annoyed me greatly in the past.

Stefan
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://www.haskell.org/pipermail/libraries/attachments/20071117/3ab4cb24/attachment.bin