My documentation of System.Posix.Files

Johan Tibell johan.tibell at
Wed Aug 9 16:16:30 EDT 2006

I've started to write some docs for System.Posix.Files but before I
finish that and move on to other packages in System.Posix.* it would
be great with some feedback on style (and grammar/spelling of course,
English is my second language).

* Currently most of the POSIX docs are rather incomplete and are in
the spirit of "read the man pages". Often a function's documentation
states what C function is called and very little beyond that. The man
pages contains a wealth of information but:

- Everyone doesn't know C (hopefully Haskell is their first language ;) )
- Everyone might not have them
- It takes longer time if you have to go and look in the man pages
- There might be subtle differences
+ They are likely to contain a more in depth information than my
documentation of the library ever will!

Perhaps I could still annotate each function with something like:

NOTE: Uses the POSIX system call stat.

Or something like that. Perhaps put a mapping of functions to C calls
in the module description.

* Perhaps I should put a general description of terms (symbolic links,
everything is a file, etc.) in the module description?

* Lots of error conditions are undocumented. I added some references
to a function called throwErrnoIfMinus1_ which lives in
System.Posix.Error. It is currently undocumented and frankly it looks
like something that "should" be an internal function. Perhaps I could
just mention which computations might throw an IOError?



More information about the Libraries mailing list