My documentation of System.Posix.Files
simonmarhaskell at gmail.com
Thu Aug 10 06:21:09 EDT 2006
Johan Tibell wrote:
> 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).
I took a brief look, and it seems fine. Thanks!
> * 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.
Certainly, most of the System.Posix functions correspond fairly directly to the
underlying POSIX API, so documenting which function is underlying will let
people consult the POSIX documentation which should be more complete.
In particular, the error codes are all documented by POSIX, I don't think we
should duplicate them here.
> * Perhaps I should put a general description of terms (symbolic links,
> everything is a file, etc.) in the module description?
Sure, but don't go overboard if you're just repeating stuff that's in the POSIX
documentation. A link to the POSIX docs is more useful.
> * Lots of error conditions are undocumented. I added some references
> to a function called throwErrnoIfMinus1_ which lives in
I think you could just say somewhere that "if the function fails, the errno code
is converted to an IOError using Foreign.C.Error.errnoToIOError. For a list of
which errno codes may be generated, consult the POSIX documentation for the
More information about the Libraries