The PBP suggests a way to put longer blocks of documentation in code, by using the =for or =begin/=end notation in POD. By labeling these with a “formatter” that does not exist, they’ll never be output and are merely ignored by the compiler and for the author’s use.
I love this idea, but every time I’ve tried it I’ve had to explain what it was an how it worked. I’ve had to tell every engineer who looked at it that no, it’s not part of the generated docs, and no, it’s not in the wrong place. In practice, it seems to be a hassle. If more people did it or understood the POD notation better it might be less of a struggle to do.
Often I don’t bother and use a feature of my editor to use word wrap text but keep the leading # and have a long block of comments.
(Question: is a big POD block faster than a long line of # comments?)
I also admit that I find the book’s suggestion that this one POD goes in-line with the code while the rest goes at the end to be inconsistent. But I find pod-at-the-end an abomination and think it does an enormous amount of harm, so that shouldn’t surprise anyone.