http://qs321.pair.com?node_id=397662

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

I am currently working on my diploma thesis, written in Perl of course ;-). Over time, the project grow and now there's quite a different number of modules and classes. I have a distinct feeling that in half a year, it will be much harder to understand what's going on...

When doing projects in other languages, I'm used to using a tool like Doxygen or JavaDoc to document classes and functions. However, for Perl, I am not aware of such a tool. Of course, there's POD, but it's not quite a match for Doxygen unless combined with some script that collects information from several files.

Is anybody aware of a documentation tool that I might use, or has anybody a homebrewn script that I might extend?

Thanks for your help!

Replies are listed 'Best First'.
Re: Documentation system
by jplindstrom (Monsignor) on Oct 08, 2004 at 16:29 UTC
    Take a look at Mark Overmeer's OODoc and see if that fits the bill. There are examples.

    /J

      Thanks, this looks quite perfect! I will definitely give it a try.
Re: Documentation system
by kutsu (Priest) on Oct 08, 2004 at 16:11 UTC

    Preferred method of documentation? covered a lot of documentation ideas, both systems and methods, you might look there for ideas.

    "Cogito cogito ergo cogito sum - I think that I think, therefore I think that I am." Ambrose Bierce

Re: Documentation system
by SpanishInquisition (Pilgrim) on Oct 08, 2004 at 17:58 UTC
    I am currently working on my diploma thesis, written in Perl of course ;-).
    That made a funny picture in my head...
    sub make_thesis { my $thesis = new Thesis( reference => [ new Bose::Einstein, new Quantum::Entanglement(), +new Matter::Dark ], proposed => new BackOf::GiantTurtle(), ); $thesis->prove(); # $thesis->ambigious_filler_with_big_words(); # $thesis->make_sound_important(); $thesis->lots_of_graphs(); $thesis->conclusion(); $thesis->bibliography(); return $ITS_ALL_GOOD; }

      That made my day :-). Actually, writing my thesis was as easy as that. The hard part was to write Thesis.pm, since I couldn't find it on CPAN ;-).

      Joke aside, of course I meant I wrote the software for my diploma project in Perl (using wxPerl). The thesis itself is written in a mixture of German and LaTeX. As soon as I have finished off various things, I'll probably write a meditation about it.

Re: Documentation system
by slagel (Novice) on Oct 08, 2004 at 16:04 UTC
    I've always had the same desire, POD just doesn't do enough for me and I've always been jealous of the clean way java does it with javadoc. We just ended up writing our own script to do this, maybe I'll get it posted so others can use it.

    I've heard somewhere out there their is a script that will allow you to use doxygen with perl, I don't remember the link but I think you can find it from the doxygen web site.

    Another tool you might want to look at is pdoc.

Re: Documentation system
by jimbojones (Friar) on Oct 08, 2004 at 16:28 UTC

    Hi

    One cheesy thing that you could do is to use Doxygen by putting all the Doxygen comments after an __END__.

    #-- Perl script print "Test Perl Script\n"; __END__ /*! \class Test \brief A test class. A more detailed class description. */

    You'd have to use the "Documentation at other places" format and you'd wouldn't get any of the source scanning features.

    The other problem is that the .pl extension isn't recognized. You'd either have to work on the Doxygen source, or write a wrapper script that linked your .pm files to a recognized extension. This hack creates problems in the doc itself, because it says things like

    was generated from the following file: * test2.cpp
    instead of
    * test2.pm

    Also, based on some of the other posts, it appears there is a Perl-to-Doxygen script call DoxyFilt. However, I couldn't connect to that site. It appears to read the POD and parse the module to create pseudo-C files with the Doxygen comments.

    - jim
      After some googlification, I got a link to access all the files of DoxyFilt : ftp://ftp.doorways.org/doxyfilt Seems like the project is not maintained anymore though. - G.
        There is a somewhat recent version (a few months old), and after fixing two typos, it works rather well for me. I think I prefer this to OODoc, actually.
Documentation system -- Important note on OODoc
by crenz (Priest) on Oct 12, 2004 at 17:09 UTC

    A quick update in-between: I tried out OODoc, but I'm not sure whether it fits the bill. It's very module-oriented; I couldn't get it to include docs from my .pl files. I want to document the whole project, not just the classes. Still, I'll try to take further looks at it.

    I have an important warning, though: OODoc can delete your files if you are not careful. The example given in the manpage will filter your source and replace the files with files without documentation. When I used that example, it replaced all my files with empty files :-( . Fortunately, I use Subversion, so that was not much of a problem. However, without a backup, these files would have been lost.

    If you try out OODoc, make sure you work on a copy and use something like this

    $doc->processFiles( source => $distdir, workdir => undef, version => '0.1');

    instead of the call to processFiles in the manpage until you know and understand what OODoc does. This will keep your source files intact, AFAIK.