Quick Start...

• Installation Guide
• Example
• Usage Instructions

Introduction

As2Dac creates JavaDoc and NaturalDocs compatible documentation comments. Items with existing comments are not auto commented.

The following auto commenting takes place…

Interface definitions

Only interface declarations not already preceded by a block comment are parsed.

• interface name
• description stub
• extended interface
• TODO Stub
• Note Stub
• Version stub
• Author stub

Interface method declarations

Only interface methods declarations not already preceded by a block comment are parsed.

• method name
• description stub
• parameter list
• parameter name
• data type
• parameter description stub
• return type

Class definitions

Only class declarations not already preceded by a block comment are parsed.

• class name
• description stub
• dynamic and intrinsic attributes are noted in the description
• extended super class
• implemented interfaces
• Usage stub
• Example stub
• TODO Stub
• Note Stub
• Version stub
• Author stub

Class method declarations

Only class methods declarations not already preceded by a block comment are parsed. Functions declared within other methods are not parsed, also functions declared as properties and defined inline will also fail to document correctly.

E.g.

public var testFunction:Function = function(){ // my code }

Would fail.

• method name
• description stub
• member access (private, public, static)
• parameter list
• parameter name
• data type
• parameter description stub
• return type

Class property declarations

Only class properties not preceeded by a block comment are parsed. Properties declared within methods are not parsed, also functions declared as properties and defined inline will also fail to document correctly.

E.g.

public var testFunction:Function = function(){ // my code }

Would fail.

• property/var name
• description stub
• member access (private, public, static)
• data type

Installation

Step 1

Mac / Linux Users

If you ain't already got perl installed, you ain't usin' no Unix variant I ever done heard of. But seriously, it's installed by default on most distributions and on all Mac Os X installs. Find it by typing ... which perl in the terminal. It should be /usr/bin/perl. As2Dac find's it using /usr/bin/env. So it should just work when you have the path setup properly (see below)

Windows users

You'll probably need to install Perl...

• You could get ActivePerl from http://activestate.com (they have a nice free version)
• Alternatively install cygwin from http://cygwin.com/ making sure you select perl from the installation options (also free, runs under a BSD/Unix emulation) untested
• Go see Perl at WikiPedia --> http://en.wikipedia.org/wiki/Perl

There's a helpful wiki for Windows users getting started with Perl

Step 2

Make sure as2dac.pl can be found in your PATH

(modifying path MacOsX/Linux - Windows)

On Windows copy the script to a folder called c:\scripts and update your PATH

On Mac / Linux copy the script to a folder called ~/scripts and update your $PATH

And that's all you should need to do.

Instructions for use

Note: Although nothing nasty should happen to your class files as a result of using as2dac, if you are testing, I'd recommend you use the -o filename option to send the output to another file.

Example

The following command:

as2dac.pl -c MyClass.as -o MyCommentedClass.as -j -a 'jason milkins' -e jason@mentalaxis.com -t -T 'TODO:Add more info'

• Reads MyClass.as (in the current directory)
• Outputs to MyCommentedClass.as (in current directory)
• Autocomments JavaDoc style comments
• Sets author to @author jason milkins / jason@mentalaxis.com
• Adds TODO notes on all documentation stubs with the custom message:
• TODO:Add more info

A visual example...

./as2dac.pl -c testfiles/Input.as -V 1.0 -t -T TODO:... -a Jason.Milkins -e jason@mentalaxis.com -l -o testfiles/Output.as

Takes testfiles/Input.as and generates testfiles/Output.as

Usage

      as2dac.pl -c filename [options]

Options

Running on a folder of files (recursive)

If you have a ton of undocumented classes that you'd like to add stubs to (really?!) you can use these handy one liners, which use find to make things work nice.

(If you are running on a SVN (or other SCM system) working copy, you'll need to use the example following)

Mac OS X and Linux / nix

From the class package root e.g. myProject/src/.

find . -name *.as -type f -exec as2dac.pl -c {} \;

Provide other options after as2dac.pl as required, the order doesn't matter.

To switch on logging...

find . -name *.as -type f -exec as2dac.pl -c {} -l \;

And to log to a file...

find . -name *.as -type f -exec as2dac.pl -c {} \; > ~/as2dac.log

Folder Recursion on SVN folders

If you are using SVN (or another SCM) you must be more careful about folder recursion.

For Subversion working copies you'll need to skip over .svn folders. The following is a basic example.

find . -name *.as -type f | grep -v *.svn | while read filepath; do as2dac.pl -c "$filepath"; done

Troubleshooting

Mac Os X and Linux/Unix

You have your perl installation somewhere as2dac can't find.

By default as2dac will use /usr/bin/env perl to locate your perl installation, if you don't have /usr/bin/env this won't work... easiest thing to do is enter

which perl

This will display the location of your system's perl installation. Paste the location shown at the top of the as2dac.pl file (replace the #!/usr/bin/env perl line)

Windows

If you are running Cygwin the instructions for Linux/Mac may help you, if you are running ActivePerl the default association for .pl files should be set to ActivePerl. If you have both installed, your system could be a little confused, especially if you are using the multiple file one-liner above.

Make sure you only have one perl installed, and if you are using cygwin, make sure your path's are expressed with forward-slashes (as opposed to the windows default, back-slashes)

Other Issues

If you have any other problems, open a new issue.