Having documented most of the methods of the main class I now understand that writing good documentation is hard. First of all it is hard to maintain a constant style in describing what a method do and what its parameters are when you are not a native English speaker. Then there are many little details that I keep changing daily because I feel that are not "right" (e.g., how to refer to the instance on which the method is running? "this instance"? "the current instance" "this"?). In general, the key problem is to understand exactly what needs explanation and which explanations should be avoided because they are state the obvious and only add weight to the prose.

So my question is: have you got examples of good library documentation? Documentation that you do not curse when you have to refer to it :), documentation that make really understand what you were looking for. Or, alternatively, have you got examples of documentation styles that should not be used?

(My library is at <https://github.com/gioele/filepath> and the live docs are at <http://rubydoc.info/github/gioele/filepath/frames>. Suggestions and patches are welcome.)