My documentation of System.Posix.Files

[Simon Marlow]

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!

> http://www.itstud.chalmers.se/~larssont/docs/System-Posix-Files.html
> 
> * 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
> System.Posix.Error.

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 
underlying function."

Cheers,
	Simon