Is there really no better way to document perl code than POD?

Question

I'm a Perl programmer for a long time, but I always have problems with documentation in POD.

When I use POD comments in the code, the code is difficult to read. When I use POD comments at the end of file, there is the danger that the documentation is not in sync with the code.

I miss a documentation style similar to Java.

/**
 * @description
 * ...
 */

I look for an easier and more intuitive documentation style. Is there such a thing?

Answer 1

Myself, I often find wanting to reproduce code entries to documentation. Yet to find how I can trick POD to read the code when podding whilst letting the code execute whilst parsing. Do I really have to settle for this:

=head1 Variables

use vars (%V &C)

=cut

use vars (%V %C)

=head2 Constants

$C{hashConstant1} = "/path/to/file"

=cut

$C{hashConstant1} = "/path/to/file";

=head2 Variables

$V{strVar1} = undef

=cut

$V{strVar1} = undef;

Then again, most languages require the double typing to document.

Answer 2

Well, POD's the accepted standard for publishing Perl documentation.

I do find it rather annoying to maintain as well; I've recently experimented with using Pod::Weaver to maintain the documentation and build it into Pod on release. It's a little bit tricky in that it's quite flexible in how you filter and build the POD, and could do with a little more documentation (in POD or otherwise). But seems promising. Still too early for me to give more of a judgement than that, but it seems promising.

Hope this helps

Answer 3

Why do you think the code is hard to read with Pod? Is the code hard to read with other code around it? Perhaps you're putting too much into a particular part of the code, instead of writing small methods, etc. Are you sure it's not your code that's hard to read?

You don't have to put all of your documentation at the end of the code. Pod is perfectly fine inline with code, allowing you to put the documentation for a subroutine or method right next to the subroutine or method.

Is there some other problem you have with Pod?

Answer 4

A quick search found Doxygen Filter which purports to allow you to use Doxygen style comments (which are very close to Javadoc) to document Perl code.

Answer 5

The only time I have had a problem with POD is when using a text editor that doesn't highlight it correctly.

Just like everything in Java this seems overly verbose:

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute  

{@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 *  

@param  url  an absolute URL giving the base location of the image
 *  

@param  name the location of the image, relative to the url argument
 *  

@return      the image at the specified URL
 *  

@see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

When compared to the equivalent Perl.

=item getImage( url, name )

This method always returns immediately, whether or not the 
image exists. When this applet attempts to draw the image on
the screen, the data will be loaded. The graphics primitives 
that draw the image will incrementally paint on the screen. 

url must be an absolute URL giving the base location of the image

name is the location of the image, relative to the url argument

=cut

sub getImage{
  my ($url,$name) = @_;

  ...
}

Answer 6

You might want to take a look at Rinci. Examples of applications which use this: File::RsyBak, Git::Bunch, App::OrgUtils.

Here's how you document modules. You declare %SPEC in your module and put documentation inside it. Each function gets its own key. There are predefined fields. Localization is supported. The formatting is done in Markdown. An example:

$SPEC{':package'} = {
    summary => 'Module to do foo',
    "summary.alt.lang.id_ID" => "Modul untuk melakukan foo",
    description => <<EOT,
Blah...
...
EOT
    links => [...],
};
$SPEC{func1} = {
    summary => '...',
    description => '...',
    args => {
        arg1 => {
            schema => ...,
            summary => ....,
            description => ...,
        },
    },
    examples => [...],
    links => [...],
    ...
};

Instead of using Java- or Perl 5 style of putting documentation in "comments", it uses data structure directly available to the programs. (Note that Perl 6 is also going this way.) Think of it as Python docstring gone crazy (or structured).

There are tools to generate POD, text, HTML from the metadata (spec). Aside from documentation, the metadata is also useful for other things like argument validation, command-line interface, etc.

Disclosure: I'm the developer.