Beefy Boxes and Bandwidth Generously Provided by pair Networks
Just another Perl shrine
 
PerlMonks  

Re: Re: Re: Inline POD vs. EOF POD

by jplindstrom (Monsignor)
on Jul 12, 2001 at 19:51 UTC ( #96079=note: print w/ replies, xml ) Need Help??


in reply to Re: Re: Inline POD vs. EOF POD
in thread Inline POD vs. EOF POD

Now you are describing a very specific situation, which is a far cry from your earlier "everyone will use inline POD if the syntax gets changed".

I don't think it was me saying that, but never mind.

The "specific situation" is one that I encounter every day: I author and maintain a number of programs/applications written in Perl. I put common stuff into general CPAN-style modules, but the actual program functionality is always a number of very domain specific classes whose interface needs to be documented. For that I use POD which I think works fine, especially since I also use a POD/module browser that will jump me right into the source when I need that.

Writing CPAN modules is another "specific sitation", although a more common one for some people.

Again -- the interface needs to be documented, the usage too. The interface should be documented near the implementation, hence inline POD. The usage should be described and explained. EOF or BOF POD is perhaps more natural in this case.

The issue of where to place POD (if that's what you like best) is maybe not "either-or", rather "both", since both are needed.

New revised personal preference :)

  • Usage: POD
  • Interface: Inline POD
  • Implementation: Perl Comment

/J


Comment on Re: Re: Re: Inline POD vs. EOF POD

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (11)
As of 2014-09-18 07:47 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    How do you remember the number of days in each month?











    Results (109 votes), past polls