How to document code in practice

This section of the manual does not deal with the specifics of organizing documentation in the peardoc standard, but instead with how to organize documentation logically. To learn about authoring documentation files in peardoc format, please look in PHP's CVS here.

Follow a few basic rules when documenting a package, and you will have good documentation.

First, every package solves a problem. What is this problem? Try to figure out what assumptions your end-users might not have about the problem (they may not realize that this is a problem that needs solving). For instance, a template package solves the problem of both separating design from code, and separating business logic from display logic. If possible, explain the problem in terms that even a beginning programmer could understand.
Next, how does the package uniquely solve the problem? This is something that most documentation lacks. For example, there are many template engines. All of them solve the same problem, but none of them do it in the same way. A block-based template engine does not have any logic at all, whereas a template like Smarty defines a whole new template language. Some template engines compile their templates, others don't. What is unique about your package? Can someone who has never seen the code get a good idea of how it solves the problem?
Last, every publicly accessible aspect of the package must be thoroughly documented. If your package is a re-usable class, document every method that users should expect to use. If your package has constants that are publicly accessible, document their meaning and where they should be used. Document any interfaces that users must use, such as a database DSN, command-line arguments for applications, configuration file contents, or any other non-code element.
Include at least 2 code examples: one simple and one complex. This is obvious, but PEAR packages are designed to be used: show your users how to use them! :)
Last, proofread your documentation. If possible, have someone else who is not as familiar with your project take a look at the documentation. They will catch assumptions that you have missed. This is probably the most important step of all.