Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot
 
PerlMonks  

Re^2: good examples of POD documentation

by JavaFan (Canon)
on Mar 06, 2009 at 14:19 UTC ( [id://748864]=note: print w/replies, xml ) Need Help??


in reply to Re: good examples of POD documentation
in thread good examples of POD documentation

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.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://748864]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others wandering the Monastery: (3)
As of 2024-03-29 02:16 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found