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). 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. 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? Cheers, Johan
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
participants (2)
-
Johan Tibell -
Simon Marlow