This is personal, but I taught myself how to code, before the internet, and with barely any books. One thing that made, for example, the PHP documentation a lot easier to read vs. Perl was: examples
On an API level, don't just explain what things do, but how to use it, what is the intention behind a particular call or method, and how it integrates with other pieces of the environment. If there are best practices, this is the place to call them out. And it does not need to be a tutorial, but if the class calls for a "usage sample", that is perfect for the documentation.
Pick on these:
1) What decisions did you take for the implementation?
2) What tradeovers are made (this is written like this because ...)
3) How is it supposed to be used
4) What is the common pattern for accessing the resource (instantiate it, factory, singleton, dependency injection?)
5) How does it relate with the rest of the codebase?
Now, this is PHP, but on other languages...
6) Is it Thread-Safe?
7) How cheap is it to instantiate a new object of that type?
These are some very good points! I already try to explain in my documentation why I wrote the code like I did, but I guess I'm afraid I'll bore the reader to death with it. Describing common patterns, or good practices is also something I try to do regularly.
The relation to the rest of the codebase is something I don't really get: do you mean I should explain why this piece of code is consistent with other code? Or the documented code interacts with other pieces of code?
I would imagine the relation to the rest of the codebase is how/why it interacts with the rest of the code. This is often valuable to know as its rare you are using just a single piece of a codebase in isolation, and relations among pieces are very helpful for developing intuition about them and the codebase as a whole.
On an API level, don't just explain what things do, but how to use it, what is the intention behind a particular call or method, and how it integrates with other pieces of the environment. If there are best practices, this is the place to call them out. And it does not need to be a tutorial, but if the class calls for a "usage sample", that is perfect for the documentation.
Pick on these: 1) What decisions did you take for the implementation? 2) What tradeovers are made (this is written like this because ...) 3) How is it supposed to be used 4) What is the common pattern for accessing the resource (instantiate it, factory, singleton, dependency injection?) 5) How does it relate with the rest of the codebase?
Now, this is PHP, but on other languages... 6) Is it Thread-Safe? 7) How cheap is it to instantiate a new object of that type?