Beefy Boxes and Bandwidth Generously Provided by pair Networks
Do you know where your variables are?
 
PerlMonks  

Re^2: Documentation: POD vs Comments

by JavaFan (Canon)
on Jul 22, 2011 at 14:19 UTC ( #916145=note: print w/ replies, xml ) Need Help??


in reply to Re: Documentation: POD vs Comments
in thread Documentation: POD vs Comments

Therefore you make the maintainer's life easy by putting POD as close as possible to the bits of code that it documents.
That's quite subjective. If *I* were the maintainer, you wouldn't score any brownie points.

But, as you said, POD isn't there for the maintainer - it's there for the user. POD doesn't have any way of modifying the order in which it appears in the source file. While there are some cases where you may present the documentation in the same order as the corresponding code appears in the source file, IMO, more often than not, that's not in the benefit of the user. My POD often contains sections that aren't directly related to any specific code (usually, only parts of the DESCRIPTION describe code), and those that do, I usually want to present them to the user in a different order. I may want to describe often used or general functions/methods before less often used, or specialist functions/methods. And sometimes I want to describe my methods in alphabetical order.

Interleaving POD with code means that the flow of your manual page depends on how the code was written. This is a case of "implementation shining through". Which I think is a thing that should be avoided.


Comment on Re^2: Documentation: POD vs Comments

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others perusing the Monastery: (12)
As of 2014-12-17 21:08 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (34 votes), past polls