Re: Large-scale code documentation

[tachyon]

documentation generator? web-enabled perldoc? covers a fair bit of ground. The perldoc project looks like it died but might help you out.

Before doing anything I would start by putting it all under CVS (Short tutorial) With CVS you get a nice cohesive location for backup etc as well as all the other benefits. Then I would simply use Pod and refactor as I went. POD::HTML will give you some nice docs and you can use CVS to rollback any misfactors.

A significant problem with autodoc generation is the parsing stage. B::Xref does a reasonable job if you were looking to roll your own.

perl -MO=Xref script.pl 2>errs 1>output

Unpatched it creates a ream of warnings about unit vars, thus the 2>errs. If you examine the output you will see info like this. I ran it on UNIVERSAL.pm as this is a nice short 10 lines, the more complex the code, the more output you get.

$ head UNIVERSAL.pm

package UNIVERSAL;

# UNIVERSAL should not contain any extra subs/methods beyond those
# that it exists to define. The use of Exporter below is a historical
# accident that should be fixed sometime.
require Exporter;
*import = \&Exporter::import;
@EXPORT_OK = qw(isa can);

1;


$ perl -MO=Xref UNIVERSAL.pm

File UNIVERSAL.pm
  Subroutine (definitions)
    Package UNIVERSAL
      &VERSION          s0
      &can              s0
      &isa              s0
    Package attributes
      &bootstrap        s0
  Subroutine (main)
    Package Exporter
      &import           7
    Package UNIVERSAL
      *import           7
      @EXPORT_OK        8
UNIVERSAL.pm syntax OK
$

It includes a lot of the info you need to automatically generate docs and will show lexical as well as global vars.