Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

(ichimunki) Re: Inline POD vs. EOF POD

by ichimunki (Priest)
on Jul 09, 2001 at 19:55 UTC ( #95016=note: print w/ replies, xml ) Need Help??


in reply to Inline POD vs. EOF POD

So far I haven't seen a comment that echos my thoughts. But I like both inline and EOF POD for two different purposes.

Inline works great when you are writing a module, you put some POD at the beginning and the end of the file, but it's nice to have the documentation for the methods right next to the code. This still produces a very usable perldoc page.

But for the end-user application (and I assume that this is either a shorter script or the glue script for a set of modules) I'd just put the whole POD either at the start or the end of the file since it is probably not necessary (or even desirable) to use POD to comment code.


Comment on (ichimunki) Re: Inline POD vs. EOF POD
(tye)Re: Inline POD vs. EOF POD
by tye (Cardinal) on Jul 09, 2001 at 20:19 UTC

    Inline POD certainly restricts the possible format of your documentation. Win32::TieRegistry's documentation would suck by comparison if I tried to use inline POD for it.

    The advantage of inline POD is that you can keep the documentation of the interface close to the definition of the interface. The problems with that are that 1) good POD should contain a lot more than just the documentation of the interface and 2) Perl doesn't let you define an interface other than via its implementation.

    So inline POD forces the co-mingling of the implementation and lots of non-interface documentation (like examples, explanations, etc.). This can easily make the implementation fragmented and harder to understand/maintain and make the documentation fragmented and harder to understand/maintain.

    Now, if Perl offered interface declarations (like subroutine prototypes in many other languages), then I'd likely co-mingle those into the POD.

    But I mostly don't use co-mingled POD because I think it leads to pretty ugly documentation. I like to control the flow of the documentation in hopes of making it easy to understand and also control the flow of the code for the same reason. These goals usually don't lead to the code being in the same order as the POD so I usually don't co-mingle them.

    Update: Yes, Perl subroutine declarations, especially of OO methods, only define a name and so are pretty useless. If Perl had "more traditional" subroutine declarations, than changing the interface w/o updating the documentation (where the declaration is co-mingled) should produce an error about mismatched prototypes in order to remind you to update the documentation.

            - tye (but my friends call me "Tye")
      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

        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

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others imbibing at the Monastery: (15)
As of 2014-07-11 17:48 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    When choosing user names for websites, I prefer to use:








    Results (232 votes), past polls