I've traditionally thought of code comments as having two audiences. One audience is me, or whomever will be taking over the code after me. This consists of notes or hints as to what I was thinking when I wrote something. Typically these are regular code comments, possibly right on the end of a line. The second audience is the users of my code. Usually this is other programmers, in the case of a library (as opposed to the consumer of a resulting UI, which I guess is a sort of third non-engineer audience who doesn't read code comments). This second group is the one for which you typically use POD (or similar in other languages - javadoc).
