Perl Script Documentation

Anonymous Monk has asked for the wisdom of the Perl Monks concerning the following question:

I have just started working with my own modules and find that using Perldoc to display information about what I have created great. The documentation is inline and describes the code immediately following the remark this makes documentation cleaner and allows review of the code much easier. Formating is another Plus!

Does anyone see a disadvantage (other than it does not currently work) to using the same documentation format in PLs that are used in PMs.

So for example script -h will automatically call perldoc script and display inline documentation.

Comment on Perl Script Documentation

Replies are listed 'Best First'.
Re: Perl Script Documentation by Sweeper (Pilgrim) on Oct 30, 2001 at 11:28 UTC
By the way, here is a URL which describes what should appear in a program POD: http://world.std.com/~swmcd/steven/perl/program_pod.html And there are also interesting links in http://world.std.com/~swmcd/steven/perl/ Update Followed tye's advice to format URL. Thanks tye.	[reply]
Re: Re: Perl Script Documentation by Anonymous Monk on Oct 30, 2001 at 12:44 UTC
Thanks, I will be using this style of documenting in my next script.	[reply]
(jeffa) Re: Perl Script Documentation by jeffa (Bishop) on Oct 30, 2001 at 09:36 UTC
By PLs i assume you mean scripts, whereas PM's are modules. At any rate, you sure can use POD in scripts (it works!), and you can see the documentation for any file you specify by using the -F option when you invoke perldoc. As per programming style, i leave the -h option in my scripts limited to one or two lines. If you want more, use perldoc. :) jeffa	[reply]
Re: (jeffa) Re: Perl Script Documentation by arhuman (Vicar) on Oct 30, 2001 at 13:30 UTC
By the way, shouldn't it be .plx instead of .pl (according to the Camel) ? "Only Bad Coders Code Badly In Perl" (OBC2BIP)	[reply]
Re: Perl Script Documentation by Fletch (Bishop) on Oct 30, 2001 at 17:12 UTC
Pod::Usage might be of tangental interest. It'll basically dump the SYNOPSIS section from your pod out. And it's core as of 5.6.1.	[reply]