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

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 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?