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
[download]

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
$
[download]

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

1. I print out all of the code with pr -f -l55 | lpr. Three hole punch the pages, put them in notebooks. The top of each page will have the filename and date, so you should not get these pages mixed up with others that you might create later.
2. Get out several highlighters and mark the beginning of ever package and sub, using different colors. Then highlight with vertical indented arrows the nested loops and blocks, etc.
3. Make sure that all of the code is in a source code control system so that if I screw up, I can go back.
4. Then, I sit back down at the computer editing program (I prefer Emacs), and start writing comment lines.
5. When I think that I understand the how and why of functions and section of code, I write the POD entry right above the beginning of that blocks. POD can be specified for specific interpretors, so you can do HTML specific image references if you wish. This can all be done in a later pass throught the code.

Thanks. I have already printed out some of the code and highlighted different areas. Like you, I enjoy having the code on paper (although that's a lot of paper).

Why would having the code in a source code control system be vital? In addition to the volume print outs, I also save a copy of any files I am working on and then test my changes. I will also be the only person modifying the code... Are there any benefits of a code control system that I am missing?

A source code control system allows you to go back to previous versions and do comparsions of versions. This is important because it is not uncommon to break one thing while fixing another. The version comparisons help figure out how that might have happened.

Secondly, source code control systems are an efficient storage method because they store only the changes to files rather than multiple copies of the files.

Thirdly, despite the extra pain in the neck that CVS and similar systems are to administrate, they allow multiple copies of the code to be checked out (usually by different people). When the people commit their additions and revisions, the system looks to see if there are conflicts in the areas that have been worked on. It demands that the conflicts be resolved before a new version is released.

Another benefit of all of these systems is that they enforce a certain discipline of documenting what you have worked on. Actually, I have found that documentation more useful for billing or job review than I have for benchmarking the progress of a job, which is its original intent.

You may think that only you will be working on this code, and that may be very true. But, you 12 months from now, after working on some other branch of this project or some entirely different project, you will appreciate any structure and documention that exists. It will help you get back into the depths of the code elements.

perlcapt
-ben

TidyFoo

You can use Class::Contract and Params::Validate to create a syntax of "how stuff should work," from which you can write a lexer to create documentation for. Hardish work, but very rewarding when it works.

--
Tilly is my hero.