Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

Generating documentation from Perl code (not just POD)

by aufflick (Deacon)
on Jul 11, 2006 at 05:15 UTC ( #560312=perlquestion: print w/ replies, xml ) Need Help??
aufflick has asked for the wisdom of the Perl Monks concerning the following question:

What I'd like to do is be able to generate documentation of classes, methods, inheritence etc. from Perl code itself (either via parsing or introspection - both have their downfalls).

Ideally a script/module would do that, and also interleave the POD from the file, so any POD directly before the method/sub would be linked to it. Any method/sub without POD would at least be documented by it's name.

Of course a major limitation is that (for OO Perl at least), we have no idea what the method arguments are, simply from robotically inspecting the code. Something I always liked in OpenACS is the way that they replace the builtin Tcl proc keyword with a custom ad_proc keyword that works just the same as proc but which takes an optional documentation block that accepts javadoc-like keyword embedding and also a block detailing any arguments and their default values. Because of the tight coupling, the generated documentation is very rich for little developer effort.

Does anyone know of attempts at this sort of thing in Perl, or have any good ideas to offer? Ideally I want to come up with something that will work with existing Perl code, and that any extensions won't break normal Perl compilation (no literate programming preprocessors need apply).

/Mark

Comment on Generating documentation from Perl code (not just POD)
Re: Generating documentation from Perl code (not just POD)
by planetscape (Canon) on Jul 11, 2006 at 06:27 UTC
      Wow - Doxygen + Doxyfilt is *exactly* what I was looking for - fantastic!

        Glad to hear it! :-D

        If you have any questions about configuring Doxyfile to run Doxygen/DoxyFilt under Cygwin, for instance, please /msg me.

        HTH,

        planetscape
        Wow - Doxygen + Doxyfilt is *exactly* what I was looking for - fantastic!

        Now, please someone with influence sell the P6 guys on Doxygen. Let's have it built into the language and allow the terminally-ill POD slip away peacefully.


        Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
        Lingua non convalesco, consenesco et abolesco. -- Rule 1 has a caveat! -- Who broke the cabal?
        "Science is about questioning the status quo. Questioning authority".
        In the absence of evidence, opinion is indistinguishable from prejudice.
Re: Generating documentation from Perl code (not just POD)
by philcrow (Priest) on Jul 11, 2006 at 13:41 UTC
    I'm interested in this area. Once, in the past, I wrote UML::Sequence which runs perl programs to produce sequence diagrams of what they actually do. This leads me to think that you could write a special driver using the debugger hooks to load the modules from your app, then dump out their inheritence relationships, etc. (based on what is loaded and what those modules have in their @ISA and symbol tables). Maybe that could be incorporated with some good POD parsing, but I'm just rambling now.

    Phil

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: perlquestion [id://560312]
Approved by planetscape
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others cooling their heels in the Monastery: (10)
As of 2014-12-26 19:07 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    Is guessing a good strategy for surviving in the IT business?





    Results (174 votes), past polls