NAME

Pod::FromActionscript - Convert Actionscript documentation to POD

SYNOPSIS

use Pod::FromActionscript (asdoc2pod);
asdoc2pod(infile => "com/clotho/Foo.as", outfile => "com.clotho.Foo.pod");
asdoc2pod(infile => "-" outfile => "-");
asdoc2pod(infile => \*STDIN, outfile => \*STDOUT);
asdoc2pod(in => $ascontent, out => \$podcontent);

or use the asdoc2pod command-line program included in this distribution.

DESCRIPTION

Parse Actionscript code, searching for Javadoc-style comments. If any are found, convert them to POD (Perl's Plain Old Documentation format). The output is just the POD, unless the code flag is used, in which case the original Actionscript is output with the Javadoc converted to POD.

Only a limited subset of Javadoc commands are understood. See below for the full list. Any unrecognized directives cause parsing to abort. Future versions of this module should handle such failures more gracefully.

LICENSE

Copyright 2005 Clotho Advanced Media, Inc., <cpan@clotho.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

FUNCTIONS

asdoc2pod OPTIONS...

Convert Javadoc-style comments embedded in Actionscript code into POD. The arguments are key-value pairs as follows:

in => SCALAR

The input Actionscript code as a string.

infile => FILENAME

infile => FILEHANDLE

Read the Actionscript code from a file. If the value is a reference, it is assumed to be a filehandle. If it is a scalar, it is assumed to be a filename. If the filename is -, then code is read in from STDIN.

out => SCALARREF

The output POD, or an empty string if no Javadoc is detected, is assigned to the specified scalar reference.

outfile => FILENAME

outfile => FILEHANDLE

Write the POD to a file. If there is no POD found, the no data is written. If the outfile value is a reference, it is assumed to be a filehandle. If it is a scalar, it is assumed to be a filename. If the filename is -, then POD is written to STDOUT.

verbose => BOOLEAN

If true, some debugging information is printed. Defaults to false.

code => BOOLEAN

If true, then the Actionscript code is included in the output, with the Javadoc comments replace with appropriate POD comments. If false, then just the POD is output, with the code omitted. Defaults to false.

SEE ALSO

JavaDoc-style Actionscript documentation (sometimes called ASDoc) derives from Sun's JavaDoc system. The official JavaDoc page: http://java.sun.com/j2se/javadoc/

Here are some actively-developed non-Perl tools that can also render Actionscript comments. None of these do POD, but that's not always a drawback.

VisDoc

Commercial, Mac OSX only. This one makes very pretty HTML output.

http://visiblearea.com/visdoc/

as2api

Ruby, GPL (I think), cross-platform, fairly well documented. The URL below contains links to a lot of other parsers.

http://www.badgers-in-foil.co.uk/projects/as2api/

AS2Doc

Commercial, Windows-only. I haven't tried it.

http://www.as2doc.com/

AS2Docular

Free, web-based, in development (will be released "soon"), HTML output only. Supports Dreamweaver template syntax.

http://www.senocular.com/projects/AS2Docular/help.php

ACID

Python, Windows only, no license specified, HTML output. The code is uncommented and nearly unintelligible.

http://icube.freezope.org/acid

COMPATIBILITY

Here is a list of all of the POD/Javadoc directives that are understood. I distinguish between one line directives (terminated by a new line) and block directives (terminated by the end of the comment or the start of a new directive.

NAME

This is a POD-specific, one-line heuristic. If the first line of the comment above the class/interface declaration has a pattern like <word> - <words> then it becomes a =head1 NAME block.

DESCRIPTION

This is a POD-specific, block heuristic. After all other ASDoc directives have been parsed out of the comment above a class/interface declaration, all remaining text is put in a =head1 DESCRIPTION block.

API

This is a POD-specific heuristic. A =head1 API block is started just before the first function declaration.

FUNCTION

This is a POD-specific, block heuristic. Each comment above a function declaration becomes an =item block. After all ASDoc is parsed from the comment, the remainder is added as prose below the =item.

PROPERTY

This is a POD-specific, block heuristic. Each comment above a property declaration becomes an =item block. After all ASDoc is parsed from the comment, the remainder is added as prose below the =item.

Because a property may be a pointer to a function, all function declaration directives are also valid in property declarations.

PROPERTY DEFAULT VALUE

This is a heuristic that adds a Default value: comment above a class or instance property that has an intial value set.

@author

This one-line directive becomes a =head1 AUTHOR block. It can only appear in a block just above the class/interface declaration.

@license

This block directive becomes a =head1 LICENSE block. It can only appear in a block just above the class/interface declaration.

@see

This one-line directive becomes a =head1 SEE ALSO block. It can appear above a class/interface declaration, a function declaration or a property declaration.

TODO: Add L<> tags around links.

@param

Every one-line @param directive above a function declaration becomes an argument entry in the function comment just above any prose comments.

@returns

A one-line @returns directive above a function declaration becomes a line in the function comment just below any prose comments.

{@code ...}

This delimited block can appear anywhere. It is converted to a C<...> block.

AUTHOR

Clotho Advanced Media Inc., cpan@clotho.com

Primary developer: Chris Dolan