Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says "Inspired by some paper (http://www.ogi.edu/csee/~mpj/)" and then just shows you a bunch of type signatures, without telling you *anything* about what the module is supposed to be for, or what all these classes, types, methods and functions are meant to *do*? I'm currently struggling with a really knotty problem, and the last thing I need is unhelpful documentation. :-S (Did I mention that that URL goes nowhere?)
Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says
"Inspired by some paper (http://www.ogi.edu/csee/~mpj/)"
It's probably because it was felt that the paper itself is better documentation than anything that could be written in the comments. Of course, this may or may not be actually true. It just seems to be a particular quirk of the way the Haskell community generates, disseminates, and consumes information. Is there a particular module you're having trouble with? Or just griping in general? =) -Brent
Is there a particular module you're having trouble with? Or just griping in general? =)
How about STM? It would be nice if I didn't have to scan the paper each time I do something with STM. Isn't that the point of having an API reference?
-Brent
Tim Newsham http://www.thenewsh.com/~newsham/
On Tue, 3 Jul 2007 09:23:02 -1000 (HST)
Tim Newsham
How about STM? It would be nice if I didn't have to scan the paper each time I do something with STM. Isn't that the point of having an API reference?
-Brent
Tim Newsham http://www.thenewsh.com/~newsham/
What is missing in STM's documentation? TArray, TChan, TMVar have just as much documentation as their non-transactional counterparts. The documentation for TVar and STM is also available, but perhaps more difficult to find. Note that Control.Concurrent.STM.TVar (similarly Control.Monad.STM) does not have any documentation on the page, but each identifier is a link to GHC specific modules that give more documentation. This is a bug in Haddock: it doesn't know how to include documentation from another package. Cheers, Spencer Janssen Documentation: http://www.haskell.org/ghc/docs/latest/html/libraries/stm/Control-Concurrent... http://www.haskell.org/ghc/docs/latest/html/libraries/base/GHC-Conc.html#t%3... http://www.haskell.org/ghc/docs/latest/html/libraries/stm/Control-Monad-STM.... http://www.haskell.org/ghc/docs/latest/html/libraries/base/GHC-Conc.html#t%3... etc.
Tim Newsham wrote:
Is there a particular module you're having trouble with? Or just griping in general? =)
How about STM? It would be nice if I didn't have to scan the paper each time I do something with STM. Isn't that the point of having an API reference?
Similar remarks hold for Parsec. The online manual is very well done, and I learned the thing easily and painlessly. But the online documentation is one 1,000 mile long HTML page. On the other hand, the nicely browsable API docs contain virtually nothing except the type signatures... On the one hand, in Haskell (unlike any other language I've ever seen) you can often *almost* tell what something does just form the type. (Pretty amazing, really.) OTOH, sometimes you can't...
On Tue, 2007-07-03 at 15:11 -0400, Brent Yorgey wrote:
Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says
"Inspired by some paper (http://www.ogi.edu/csee/~mpj/)"
It's probably because it was felt that the paper itself is better documentation than anything that could be written in the comments. Of course, this may or may not be actually true. It just seems to be a particular quirk of the way the Haskell community generates, disseminates, and consumes information.
Actually, the code was documented in comments in the code, just not in haddock format. :-( Fortunately, some kind soul has gone through and converted the documentation to haddock format: http://hackage.haskell.org/trac/ghc/ticket/1410 So it'll all appear in the html docs in the next version. In the mean time one can look at the haddock comments in the source: http://darcs.haskell.org/packages/mtl/Control/Monad/ Duncan
| Fortunately, some kind soul has gone through and converted the | documentation to haddock format: | http://hackage.haskell.org/trac/ghc/ticket/1410 | | So it'll all appear in the html docs in the next version. In the mean | time one can look at the haddock comments in the source: | http://darcs.haskell.org/packages/mtl/Control/Monad/ Furthermore, you can always get the GHC HEAD documentation here http://www.haskell.org/ghc/dist/current/docs
From there you can get to Control.Monad, which indeed shows at least some documentation.
Simon
On Wed, 2007-04-07 at 08:03 +0100, Simon Peyton-Jones wrote:
| Fortunately, some kind soul has gone through and converted the | documentation to haddock format: | http://hackage.haskell.org/trac/ghc/ticket/1410 | | So it'll all appear in the html docs in the next version. In the mean | time one can look at the haddock comments in the source: | http://darcs.haskell.org/packages/mtl/Control/Monad/
Furthermore, you can always get the GHC HEAD documentation here http://www.haskell.org/ghc/dist/current/docs
From there you can get to Control.Monad, which indeed shows at least some documentation.
Simon, if the less-talented among us (like me) want to contribute to
GHC's docs -- and especially documenting the libraries -- what's the
best way to go about this? I'm not too comfortable with the notion of
just going into GHC's guts and Haddocking the comments, contributing
patches willy-nilly because I'd not be certain I did the job right, that
I explained things correctly where I had to amplify, etc. Is there some
kind of documentation team we poor souls could interact with to assist?
--
Michael T. Richter
Simon, if the less-talented among us (like me) want to contribute to GHC's docs -- and especially documenting the libraries -- what's the best way to go about this? I'm not too comfortable with the notion of just going into GHC's guts and Haddocking the comments, contributing patches willy-nilly because I'd not be certain I did the job right, that I explained things correctly where I had to amplify, etc. Is there some kind of documentation team we poor souls could interact with to assist?
there was the idea of using the wiki for developing documentation improvements, prior to actually submitting the improved texts. the only hint of that scheme i can find right now is: http://www.haskell.org/haskellwiki/Improving_library_documentation but establishing a documentation team to help organise the process and to define a realistic workflow (how and where to edit, how and who submits when its "ready", how to avoid extra work due to working in different formats, ..) seems like a good idea. go for it!-) claus
Claus Reinke wrote:
Simon, if the less-talented among us (like me) want to contribute to GHC's docs -- and especially documenting the libraries -- what's the best way to go about this? I'm not too comfortable with the notion of just going into GHC's guts and Haddocking the comments, contributing patches willy-nilly because I'd not be certain I did the job right, that I explained things correctly where I had to amplify, etc. Is there some kind of documentation team we poor souls could interact with to assist?
there was the idea of using the wiki for developing documentation improvements, prior to actually submitting the improved texts. the only hint of that scheme i can find right now is:
http://www.haskell.org/haskellwiki/Improving_library_documentation
but establishing a documentation team to help organise the process and to define a realistic workflow (how and where to edit, how and who submits when its "ready", how to avoid extra work due to working in different formats, ..) seems like a good idea. go for it!-)
Of course, the visionary solution would be to wikify the haddocks themselves: imagine to simply point a browser to the documentation and edit it in-place. I think that web-browsers are not ready for that, though: editing things in an extra input box after being redirected to a "edit this page" version just sucks for me, especially for the intended haddock editing. The dream is to have WYSIWYG editing in-place (modulo keyboard/mouse control. Mathematica's front-end comes close to what I have in mind.). Why to learn and adjust wiki markup on a separate page? It's not difficult but it's unnecessary and thus wasted time. Regards, apfelmus
Brent Yorgey wrote:
Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says
"Inspired by some paper (http://www.ogi.edu/csee/~mpj/ http://www.ogi.edu/csee/%7Empj/)"
It's probably because it was felt that the paper itself is better documentation than anything that could be written in the comments. Of course, this may or may not be actually true. It just seems to be a particular quirk of the way the Haskell community generates, disseminates, and consumes information.
It's probably damn useful to have the paper *as well*. You know, for some context, a nice overview, introductory material, etc. (I mean, if the link worked...) It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something...
Is there a particular module you're having trouble with? Or just griping in general? =)
After many hours tying my brain in knots, I *think* I need to use a monad transformer... but I've never ever done that before. So I'd like to learn how it works. (And then I'd like to figure out what standard monads are out there and what they do.) But the docs aren't helping me greatly in this regard. (I notice the Wiki is also somewhat devoid of any material on this subject...) Essentially I want to run a parser on top of a parser, and I think maybe this is the way to do it.
It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something...
I certainly don't disagree with you! I was just commenting on the tendency of the community to document things in academic papers. But I'm glad to hear from Duncan that better Haddock documentation will be in the next version of the libraries. After many hours tying my brain in knots, I *think* I need to use a
monad transformer... but I've never ever done that before. So I'd like to learn how it works.
Try http://uebb.cs.tu-berlin.de/~magr/pub/Transformers.en.html. I found that paper very clear and helpful in learning to use monad transformers. Then you will probably also want to read http://cale.yi.org/index.php/How_To_Use_Monad_Transformers. -Brent
Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community. It's not hard to do (grab the Darcs repo, type away), and it's widely appreciated. People often don't feel "qualified" do to this, but documentation written by an intelligent but "unqualified" person (perhaps including "not sure what happens here") is a lot more useful than no documentation at all. Yes I know that misleading documentation can be a Bad Thing but I think lack of documentation is a much bigger problem than misleading documentation, as of today. Simon From: haskell-cafe-bounces@haskell.org [mailto:haskell-cafe-bounces@haskell.org] On Behalf Of Brent Yorgey Sent: 03 July 2007 22:09 To: Andrew Coppin Cc: haskell-cafe@haskell.org Subject: Re: [Haskell-cafe] Sparse documentation It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something... I certainly don't disagree with you! I was just commenting on the tendency of the community to document things in academic papers. But I'm glad to hear from Duncan that better Haddock documentation will be in the next version of the libraries. After many hours tying my brain in knots, I *think* I need to use a monad transformer... but I've never ever done that before. So I'd like to learn how it works. Try http://uebb.cs.tu-berlin.de/~magr/pub/Transformers.en.html. I found that paper very clear and helpful in learning to use monad transformers. Then you will probably also want to read http://cale.yi.org/index.php/How_To_Use_Monad_Transformers. -Brent
Simon Peyton-Jones wrote:
Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community. It’s not hard to do (grab the Darcs repo, type away), and it’s widely appreciated.
People often don’t feel “qualified” do to this, but documentation written by an intelligent but “unqualified” person (perhaps including “not sure what happens here”) is a lot more useful than no documentation at all. Yes I know that misleading documentation can be a Bad Thing but I think lack of documentation is a much bigger problem than misleading documentation, as of today.
Simon
How exactly do I get started? (Obviously I can't write the documentation for the monad transformers - I don't know how they work yet! But I could have a go at splicing all the Parsec goodness into the Haddoc pages...)
Hi Andrew, On Wed, Jul 04, 2007 at 07:26:48PM +0100, Andrew Coppin wrote:
Writing documentation for libraries is one way in which ordinary Haskell users can really contribute to the Haskell community. It’s not hard to do (grab the Darcs repo, type away), and it’s widely appreciated.
How exactly do I get started?
(Obviously I can't write the documentation for the monad transformers - I don't know how they work yet! But I could have a go at splicing all the Parsec goodness into the Haddoc pages...)
Get the latest source: darcs get http://darcs.haskell.org/packages/parsec cd parsec Build the Cabal Setup program and configure the package: ghc --make Setup ./Setup configure Then actually update the documentation, in Text/ParserCombinators/... Now run haddock: ./Setup haddock and check that it looks reasonable. Open dist/doc/html/index.html in your web browser and follow the relevant links. It's probably also a good idea to check you haven't broken the code by accident, i.e. test that it still builds: ./Setup build If you are happy then record and send the patch: darcs record darcs send If you think that the patch might be at all contentious then you should follow the library submissions procedure instead of the last step: http://www.haskell.org/haskellwiki/Library_submissions but for just adding brief haddock docs that's probably overkill. Thanks Ian
It's also nice to have some brief comments in the API docs to say what the heck a particular module is even *for*, and provide enough info on the stuff in that module that you can quickly dip into it when you can't remember the name of something...
agreed. for me, the perldocs for most of the well-used perl packages are the gold standard. do a perldoc on the LWP or DBI modules, for example. i often find myself using a combination of the api docs and the zvon reference. examples are essential. it would be nice to merge these two documentation sources. from http://zvon.org/index.php?nav_id=legal&mime=html i see that zvon employs a form of bsd (attribution) license of course if i can help improve documentation, let me know. its one thing that novice/hobbyist haskellers can contribute effectively
Andrew Coppin wrote:
Essentially I want to run a parser on top of a parser, and I think maybe this is the way to do it.
I doubt monad transformers are the answer. I imagine you just want to one run parser over the result of the previous, which is just function composition, modulo a sensible way of handling errors. If you give more details on what you're trying, people may have helpful insights. Or not :) Jules
Jules Bean wrote:
Andrew Coppin wrote:
Essentially I want to run a parser on top of a parser, and I think maybe this is the way to do it.
I doubt monad transformers are the answer.
I imagine you just want to one run parser over the result of the previous, which is just function composition, modulo a sensible way of handling errors.
If you give more details on what you're trying, people may have helpful insights. Or not :)
Yeah, running one parser on top of another isn't inherently hard. The *hard* thing is that I want to stack several parsers on top of each other, and *change* that stack at various points in the parsing. After many hours of trying, I did eventually get working code. But *damn* it's complicated! (Especially the type signatures.) Hopefully I'll find a way to simplify it gradually... As for asking here... I did, and nobody had anything interesting to say. :-(
the references have not been updated, it seems. but once you've
used the name "Mark P Jones", mentioned next to the link, to
google for a current url for his publications page, you'll
(a) find a treasure-trove of haskell papers
http://web.cecs.pdx.edu/~mpj/
(b) be able to submit a fix for the documentation bug to the
library maintainer, which 'ghc-pkg describe mtl' lists as
libraries@haskell.org
(c) indicate to the maintainer what additional information
you would find helpful in the haddocks, and perhaps help
to get it there (several libraries have acquired more directly
useful haddocks this way, including parts of the monad libs,
with the permission of paper and tutorial authors, but there
are still quite a few gaps waiting to be filled)
(did i mention that putting bug reports in parentheses in emails
is not the best way to attract attention, get the bug recorded,
or fixed?-)
claus
----- Original Message -----
From: "Andrew Coppin"
Is there a reason why the documentation for virtually every module in Control.Monad simply begins with a line that says
"Inspired by some paper (http://www.ogi.edu/csee/~mpj/)"
and then just shows you a bunch of type signatures, without telling you *anything* about what the module is supposed to be for, or what all these classes, types, methods and functions are meant to *do*?
I'm currently struggling with a really knotty problem, and the last thing I need is unhelpful documentation. :-S
(Did I mention that that URL goes nowhere?)
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
participants (12)
-
Andrew Coppin -
apfelmus -
brad clawsie -
Brent Yorgey -
Claus Reinke -
Duncan Coutts -
Ian Lynagh -
Jules Bean -
Michael T. Richter -
Simon Peyton-Jones -
Spencer Janssen -
Tim Newsham