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).

Increasingly, however, I have decided to act as though there is only one audience. When you separate code out the way I describe above, you immediately run into a question -- what do you do for a private method? You don't expect the users of your library to call it, and yet you might have some high-level usage guide that goes beyond what you might put in an inline comment. Same thing for private instance variables, or other internal helper functions.

I've also noticed that I have two different sets of code that I write, and for each there is ultimately one audience. The first is at work. Here I am writing code that my peers will use. But my peers will also maintain the code itself. Similarly, I also write code for open-source projects. For the most part my code here will be consumed - but if and when I do actually get contributions to the library, the contributors are the consumers first and contributors second. They are pretty much exactly like the people at my work.

So I've settled on physically organizing my code into two sections, but using POD (or similar) for all of the usage or explanation-centric comments, and I treat my reader as a single audience. I put the public API methods all together, and notate them as a single section in my code, perhaps with a preamble with an example usage. I then put all of the private methods together, with a header that marks them as private -- but then I document them as if they were public. Because no matter what, from the perspective of the code IN my library, they ARE public.