How can I extract <%doc> content from Mason?

Question

Is there a tool like javadoc to extract the <%doc> content and the various methods with their parameters in Mason (Perl)? I'd like to add some basic documentation to components I'm writing and it would nice for the documentation to be auto-generated from the code.

Edited to answer question from benrifkah:

My intention was to look for a tool that functions like javadoc. It uses the comments in <%doc> and also extracts the info from <%method> and <%def> blocks.

Answer 1

While the HTML::Mason developer documentation states:

One can easily write a program to sift through a set of components and pull out their <%doc> blocks to form a reference page.

It does not look like anyone has actually done this and made their tool available to others. Since they assert that it would be "easily" done, maybe you should re-phrase the question as:

How can I write a tool to extract <%doc> content from HTML::Mason components?

Answer 2

Here is a proof of concept script that uses Text::Balanced to grab all of the <%doc> sections into an array. You should be able to use this as a starting point for a full-fledged Mason documentation tool.

#!/usr/bin/perl
use strict;
use warnings;

use Text::Balanced qw( extract_multiple extract_tagged );

my $file = 'test.mason.txt';
my $contents;
{
    local $/;
    open my $fh, $file
        or die "Unable to open $file for reading, $!\n";
    $contents = <$fh>;
    close $fh;
}

my @extracted = extract_multiple( $contents, [ sub { extract_tagged( $_[0], '<%doc>', '</%doc>', '.*?(?=<%doc>)'); } ], undef, 1 );

s!</?%doc>!!g for @extracted;

print "@extracted\n";