[superice]

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?

[natdempk]

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.