in the file but out of the way - some people feel that keeping documentation, especially lengthy documentation close to each function makes it difficult for them to get a good birds eye view of a module. This is particularly true if your team has a lot of people that are very fluent in reading code. To get POD out of the way, some people prefer to place all of the POD at the top or the bottom.I'm one of the people who puts the POD after the __END__. For the reasons you mention and for an additional reason: I often don't document the code in the same as they appear in the code. In the code, you may want to keep methods accessing the same data close to each other, but for documentation you may have other considerations. I typically use methods I expect to be used often early in the documentation, while lesser used method are documented further down. Sometimes I prefer the documentation to describe the methods sorted lexigraphical. And if the description of method A is build on the description of method B, I like to have in the documentation A right above B. Moving the documentation "out of the way" gives me the freedom of moving documentation (and code) around without changing the order.
In reply to Re^2: good examples of POD documentation
by JavaFan
in thread good examples of POD documentation
by perl5ever
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |