There's a middle ground. The path to it starts by considering that comments have the potential to be a maintenance burden. The potential for burden increases with the volume of commentary. It gets to be a major nuisance during maintenance when a 2 line change means having to rework 20 lines of commentary. Human nature being what it is, somebody is going to forget to update a comment, and the world described by the commentary can begin to diverge from the truth of the code. Having two divergent stories is a bigger liability than one truth, the code, with no commentary at all.

Pod documentation carries an additional risk, if one follows the style of locating the pod either entirely before or entirely after the code it describes. Physical distance between code and its corresponding commentary increases the likelihood that the commentary won't be updated during maintenance.

The middle ground is to locate commentary close to the code it describes, and to write as little commentary as necessary. If comments are close to the code and there isn't an excess of verbiage, chances are greatly improved that the commentary will survive maintenance.