META-PROPOSAL: Documentation should be required to say when exports were introduced
Hi all, 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. Initial deadline: 1 December 2007. Thanks Ian
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.
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
Hello Ian, Saturday, November 17, 2007, 5:13:18 PM, you wrote:
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.
may be we should construct a "Good Library" policy which includes reqs to "well-behaved" or mat be "haskeller-fiendly" lib? in particular, these rules should be required for any lib included in Haskell Standard (as i proposed) -- Best regards, Bulat mailto:Bulat.Ziganshin@gmail.com
On Sat, Nov 17, 2007 at 06:53:18PM +0300, Bulat Ziganshin wrote:
Saturday, November 17, 2007, 5:13:18 PM, you wrote:
I propose that all exports in Haskell libraries should be required to have such a thing in their haddock documentation.
may be we should construct a "Good Library" policy which includes reqs to "well-behaved" or mat be "haskeller-fiendly" lib? in particular, these rules should be required for any lib included in Haskell Standard (as i proposed)
Oh, right, when I wrote "Haskell libraries" I was thinking "all GHC bootlibs and all libraries covered by the library submissions procedure" (but it would be good if other libraries followed suit). Sorry, I should have said that in the original mail. If we decide to distinguish a set of libraries as "standard" then I agree that they, too, should be required to have versions in the docs. Thanks Ian
Hello Ian, Saturday, November 17, 2007, 7:10:05 PM, you wrote:
may be we should construct a "Good Library" policy which includes reqs to "well-behaved" or mat be "haskeller-fiendly" lib? in particular, these rules should be required for any lib included in Haskell Standard (as i proposed)
Oh, right, when I wrote "Haskell libraries" I was thinking "all GHC bootlibs and all libraries covered by the library submissions procedure" (but it would be good if other libraries followed suit).
well, it was obvious after all. what i mean here is what you will do after this proposal will be accepted? keep it as one more well-known-nowhere-written rule? i propose to make wiki page with rules for "standard libraries" which at this moment may be ones supported by libraries@ community these rules will include "submission procedure" and anything else we agree by standard process -- Best regards, Bulat mailto:Bulat.Ziganshin@gmail.com
Hi Bulat, On Sat, Nov 17, 2007 at 07:12:03PM +0300, Bulat Ziganshin wrote:
Saturday, November 17, 2007, 7:10:05 PM, you wrote:
may be we should construct a "Good Library" policy which includes reqs to "well-behaved" or mat be "haskeller-fiendly" lib? in particular, these rules should be required for any lib included in Haskell Standard (as i proposed)
Oh, right, when I wrote "Haskell libraries" I was thinking "all GHC bootlibs and all libraries covered by the library submissions procedure" (but it would be good if other libraries followed suit).
well, it was obvious after all. what i mean here is what you will do after this proposal will be accepted? keep it as one more well-known-nowhere-written rule? i propose to make wiki page with rules for "standard libraries" which at this moment may be ones supported by libraries@ community
these rules will include "submission procedure" and anything else we agree by standard process
The libraries submissino procedure is already on the wiki, here: http://www.haskell.org/haskellwiki/Library_submissions If you didn't find it linked from the wiki pages you expected, perhaps you could add links? The export-versioning would probably be used by more libraries than the library submissions procedure, so should probably have its own page, but with links between the two. Thanks Ian
participants (4)
-
Bulat Ziganshin -
Henning Thielemann -
Ian Lynagh -
Stefan O'Rear