History

Precursor Code

There is a reference to a script like this one on the Perl6 Internals list from 2002. The script was written by Bart Schuller. When I started looking for references to Perl-to-doxygen processing scripts I downloaded this script to see what it did. Thanks, Bart, it was a big help!

Primus

Quick knock-off during my work on an unrelated project. I used the precursor code as a template, but it was all written from scratch.

Secundus

Re-write from the ground up using the Primus version as a template. The precursor code, while a valuable initial input, is now fading irrevocably into the mists of time.

In this version there were two phases:

1. Parsing
2. Generation

The parser code operated by breaking input into lines and parsing as a state machine.

The code was built stand-alone, without using h2xs or any preparation for delivery to CPAN or elsewhere. The topmost namespace was C<doxy>, which turned out to conflict with CPAN naming conventions (lowercase words are for Perl pragmas).

This version was advertised on the SPUG mailing list and wiki and on the Doxygen mailing list.

Tertius

Somewhat rewritten to separate the processing phases and handle some problems caused the state machine of the Secundus version.

In this version there are three phases:

1. Parsing
2. Massage
3. Generation

This allowed Perl and POD parsing (as well as other phases yet to be imagined) to be separated. The Massage phase is where the POD items that represent functions are connected to the Doxygen items that represent functions parsed from the Perl code.

In addition, the parsing of Perl code is done by loading the entire file, removing all POD lines, and then breaking it apart into packages and functions. This works much better than the previous line-by-line state machine.

The POD parsing, on the other hand, is mainly line-oriented. This works better for the POD parts of the files.

Other parsers are their own animals.

This version was constructed using h2xs and in a (more or less) properly-named class. It is intended for eventual distribution via CPAN.