The previous examples represent a cross-section of the documentation quality of most software libraries available in the public domain. Most code is documented in some form. In many cases the code contains insufficient documentation to describe its usage. Many libraries have supplementary HTML or LaTeX manuals, which represent an additional documenting effort above and beyond code documentation. Some libraries, such as LAPACK, have complete documentation -- code documentation, reference manuals, release notes, etc. -- however this requires an enormous effort which requires many passes over the code to make the documentation fully correspond to the libraries functionality.
What is the correct style and amount of documentation? We feel that it depends on the requirements of the particular project: ultimately the documentation effort should not take additional time, but save overall as much time as possible in terms of avoiding misuse, locating bugs, and reminding the developer of her own ideas. It is therefore extremely important to assess the requirements and goals of the documentation before choosing a particular tool or set of documenting conventions.