Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

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.

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://916145]
and the fog begins to lift...

How do I use this? | Other CB clients
Other Users?
Others lurking in the Monastery: (4)
As of 2018-02-23 07:19 GMT
Find Nodes?
    Voting Booth?
    When it is dark outside I am happiest to see ...

    Results (300 votes). Check out past polls.