My documentation of System.Posix.Files
johan.tibell at gmail.com
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