Natural Doc - Create fancy documentation for your Perl code.

[Ace128]

Hey!

I just had to post about this little tool since it's so cool and I was looking for such for ages, and if it wasnt for pure chance, I wouldnt have found it and I would have tried to do my own version wasting time. So, to avoid others do the same "misstake", I post about it here.

Besides, its also MADE in Perl! How cool is that? :)

What am I talking about? Well, http://www.naturaldocs.org

So, I can just do:

# Function: myFunc
#
# Arguments:
#  1. - This object.
#  2. - Path to file.
sub myFunc {
  my ($self, $path) = @_;
}

Runing the tool on this you get some really fancy documentation. (Check out http://www.naturaldocs.org/documenting.html)

Well, thanks for your time and hope you like it.

/ Ace

[zentara]

It works, but I must admit it produces information overload for my feeble mind.... all these links, fancy names, and licenses. However, it's output would be perfect for B.S.-ing your boss that you've been working hard on that project. :-)

[Ace128]

Well, it helped me organizing some script I did with alot of functions in it! ;) Also nice to use if you wanna have overview of the script(s) you have.

[MidLifeXis]

One gripe that I have is that ND (at least the version I have) is not able to use POD in any form that can be parsed by perldoc. I do not want to write my documentation twice, and ND forces me to write it twice - once for perldoc and once for the generated documentation.

Otherwise, it is a pretty good system.

Update: Poor implication of original wording. remove and add

[Ace128]

Well, accoring to the http://www.naturaldocs.org/documenting.html:

Perl users can use POD to do block comments.
=begin nd

Function: Multiply
Multiplies two integers and returns the result.

=cut


=nd

Function: Multiply
Multiplies two integers and returns the result.

=cut

[MidLifeXis]

But if I want to have it show up under perldoc, I still have to write it twice. =begin nd blocks do not get passed through to the default perldoc formatters, only to ND.

[planetscape]

Personally, I recommend Doxygen.

Doxygen generates JavaDoc-like documentation for projects in many languages, including C and C++. DoxygenFilter is a new take on an old project (DoxyFilt) that also handles ("filters") Perl code (including POD), and now promises support for multi-programming-language projects. See Examples of output generated by doxygen, or here.

HTH,