Re: (tye)Re: Inline POD vs. EOF POD

[John M. Dlugosz]

Tye, you could declare your subs at the top mixed in with the POD. But I don't see what that would buy you, over just having the POD there.

You echo my feelings: inline POD means that the documentation follows the code's organization. Documentation needs its own organization for different purposes: tutorial, group explainations of related functions, etc. Inline documentation would also require some kind of "literate programming" process as well.

—John

[lachoy]

I'm intruiged by the potential literate programming aspect of POD (more info, see this excellent node) and, more generally, about being able to machine-generate metadata from documentation, as clemburg pointed out.

I prefer to keep information as close as possible to where I might generate it and where I might need it again -- the To Do list is the canonical example. I want to add items to my list wherever I'm programming (at the head of a subroutine, for instance) and then periodically generate all my to do items from all my code.

A natural extension of this is to keep the docs as close to the code as possible, but as has been pointed out in a number of objections here, there are real problems with this. The foremost is probably readability followed closely by, as you mention, organization.

I'm still not terribly comfortable with putting everything at the end, but I think that's what I'll probably stick with. Until something better comes along :-)

Chris
M-x auto-bs-mode

[John M. Dlugosz]

Hmm, reading the overview in that node, it seems that tangle can be implemented as a source filter, so that the LP file itself is directly shipped.