AS2Docular v0.9.6

/**AS2Docular-->

ActionScript Documentation Standalone Help  
Help Contents

Manual

What is AS2Docular?

AS2Docular is a free, web-based application used to generate HTML documentation for Flash ActionScript 2.0 (.as) files. Like other tools of its kind, it uses ActionScript comments and code to decide the content of the documentation generated. For more on correctly commenting a file for AS2Docular, see Commenting ActionScript for AS2Docular.

Unlike most of those other tools, AS2Docular gives you to control over the documentation content by way of HTML templates. These templates follow conventions similar to those found in Macromedia Dreamweaver making them (mostly) easy to create and customize on your own. Learn more about templates in the AS2Docular Template Format section.

Please note that is AS2Docular is still a work in progress. There may be still be bugs and/or undesirables. The more you use AS2Docular, the more likely they can be found and fixed. If you find a bug, please let me know.

[index]

Using AS2Docular

AS2Docular is written in PHP and requires a web server like Apache with PHP installed to run (AS2Docular was written and tested on Windows XP Pro running Apache 2 with PHP 4.3.8 using Firefox 1.0.4). If you have access to your own web server, you will most likely want to download AS2Docular for yourself to use on that web server. Otherwise, a version will always be available for use through www.senocular.com.

The AS2Docular interface is divided into four sections accessible through tabs; ActionScript, Documentation, Standalone and Help. The ActionScript and Documentation sections show files located on the server running AS2Docular and are best used with your own personal copy of AS2Docular. The Standalone section is more appropriate for using AS2Docular on a server you do not have access to such as the version running on www.senocular.com. The final section, Help, shows this manual.

The ActionScript section lists out all .as source files in the ActionScript folder located in the AS2Docular install directory. Copy any and all .as files you wish to generate documentation for in this directory. Within the listing, check boxes are provided allowing you to select which files you wish to generate documentation for. Checking a folder will select all files within that folder as well as all files within all folders within that folder. When you make your selection, make sure that those selected are properly commented. For more on correctly commenting a file for AS2Docular, see Commenting ActionScript for AS2Docular.

Once files are selected, an HTML template needs to be selected. A drop-down menu below the source file listing provides you with all available templates. These templates are those located within the Templates folder in the AS2Docular install directory. They should all have either an .htm, .html, or .dwt extension. Templates determine the style of the outputted documentation. Learn more about templates in the AS2Docular Template Format section.

Below the template selection is a list of options. These determine the behavior of AS2Docular when it creates html documentation. Adjust these as needed. Some templates may require different settings for optimal results.

Once all your selections have been made, click on the Document button at the bottom of the interface to generate HTML documentation for the selected .as files in the source file listing. Conversely, the Reset button will clear your selection and restore the form to its defaults.

Upon clicking on the Document button, you will be taken to the Documentation section where results of the operation will be provided along with a listing of all the documentation files having been generated by AS2Docular. When navigating to the Documentation section normally, the results pane will not be provided, only the list of documentation files. These files are all those located in the Documentation folder in the AS2Docular install directory. When using AS2Docular on your own server, make sure set the appropriate permissions so that this folder can be written to.

The Standalone section provides basic AS2Docular functionality to files not located on the server that AS2Docular is running. Both ActionScript and template files can be used here, either uploaded or provided as text. Those templates available to the ActionScript section are also available for use here, though ActionScript files are not.

Many of the same options available in the ActionScript section are also available to the Standalone section with the exception of Ignore TemplateBeginFile tags. This option is selected and locked as documentation from the Standalone section is restricted to one output file. That being the case, templates using TemplateBeginFile for multiple file output may not function well if at all.

Clicking on the Document button will generate documentation in a new window. You may save this documentation as needed using your browser's save option. If you see the error monkey, something has gone wrong. Double check your settings and make sure your selections are correct before trying again.

[index]

Commenting ActionScript for AS2Docular

In order for AS2Docular to correctly generate documentation for your ActionScript 2.0 file, you will need to have commented your script with definitions and explanations that describe your file; what it is, what it does, and how.

Commenting for AS2Docular largely follows the format used in Sun's JavaDoc tool for Java. Basically this involves creating block comments that start with /** and end with */ above relevant segments of code. Within these comments goes the description for the code that lies below. The following is a simple example describing a public ActionScript 2.0 property:

/**
 * The number of frames to be used in animating the selection
 */
public var frames:Number;

Additionally, within these comments, special tags can be included to represent specific information such as method parameters, return values, or really, anything you want. These tags are placed on new lines (which may or may not be preceded with an asterisk (*)) and start with a tag name immediately following an 'at' (@) symbol. Consider the following example that specifies the return value for a public method using the @return tag:

/**
 * Provides a means for obtaining the movie clip currently representing the parent
 * @return MovieClip instance
 */
public function getParentMovie(Void):MovieClip{
	// function body
}

With AS2Docular, there is no set of specific tags that you are limited to using. All tags, regardless of tag name (aside from @param, @return and @see), are treated equally. Their inclusion into the final documentation generated by AS2Docular is dependant on the HTML template used when that documentation is created.

The @param, @return and @see tags are special in that, due to their nature, require (or, at least, are given) some additional attention. The @param tag is used to describe a method parameter. It's special in that it consists of a parameter name as well as it's description. When AS2Docular reads an @param tag, it will separate the name and the description into separate parts so that you (the HTML template) can refer to them individually. Additionally, if AS2Docular recognizes that the parameter of the same name in the code is associated with a data type, that too will be added as a property of @param.

The @return tag in the comment is like most other tags, just having a description. However, as with @param, it too is given a data type based on that specified in the code.

The @see tag is used to provide references to other methods or properties that relate to the one being currently documented. Text following an @see tag should consist of only the related member's name or defintion, nothing else. If you wish to have multiple references, use a new @see tag for each. Do not use a comma separated list as that will be interpreted as one long name. AS2Docular reads @see tags differently in that it will search for another commented method or property with the specified name and associate a reference with that @see tag allowing you to possibly link to that member in an HTML template. The following method is documented with @param, @return and @see tags:

/**
 * Sets the position of the target object to a specific x,y location on the screen
 * @param xPos The horizontal position on the x axis to place the target
 * @param yPos The vertical position on the y axis to place the target
 * @see moveTargetBy
 * @see public function repositionTarget(Void):Void
 * @return True if the positioning is successful, False otherwise
 */
public function positionTarget(xPos:Number, yPos:Number):Boolean {
	// function body
}

HTML templates will be able to extract the additional properties associated with those tags for additional control in the documentation formatting process. See AS2Docular Template Format for more information on this.

Because documentation is created as HTML, the descriptions you provide may have contain HTML tags to help format their contents. In fact, if you do not include HTML tags, the result will be a single, long string of unformatted text which may run together when documentation is generated. It is recommended that HTML be included where needed to help keep your documentation nicely formatted.

One thing to keep in mind is that AS2Docular only considers definitions directly following JavaDoc comment blocks. Those not commented will be overlooked when documentation is being generated (this includes those referenced with @see tags).

[index]

AS2Docular Template Format

HTML templates are the most complicated aspect of AS2Docular, yet they are also what makes AS2Docular so flexible and customizable. Luckily you don't need to know how to create templates to make use of them; sample templates are already provided for pre-determined documentation styles. However, to create documentation that suits your taste and needs, you may want to create and use a custom template.

The HTML templates used by AS2Docular are basic HTML files that define the layout of the documentation generated for an ActionScript 2.0 file. Comment tags within the template are used to determine what content from an ActionScript 2.0 file is placed where. When the final HTML for the documentation is created, these comment tags are replaced with their respective values as interpreted by AS2Docular after having read both the ActionScript 2.0 and template files.

There following template tags are used by AS2Docular. Most are similar to commonly used Dreamweaver template tags. 

<!-- TemplateBeginEditable name="..." [type="..."] [prefix="..."] [suffix="..."] --> 
	Default value
<!-- TemplateEndEditable -->
	
	
<!-- TemplateBeginIf cond="..." [type="..."] [prefix="..."] [suffix="..."] [default="..."] --> 
	Content
<!-- TemplateEndIf -->
	
	
<!-- TemplateBeginRepeat name="..." [type="..."] [prefix="..."] [separator="..."] [suffix="..."] [default="..."] --> 
	Repeated content
<!-- TemplateEndRepeat -->
	
	
<!-- TemplateParam name="..." type="..." value="..." -->


<!-- TemplateBeginFile -->
	File/output name
<!-- TemplateBeginFile -->

Note: Properties surrounded by brackets ([]) represent optional properties. Tags are case sensitive.

  • TemplateBeginEditable: Represents a value from the ActionScript 2.0 file. This can represent a value from the comment used to describe a section of code, or a value from the line of code directly following that comment.
  • TemplateBeginIf: Tests for whether or not a property name exists. If the condition is satisfied, the contents of the block is used
  • TemplateBeginRepeat: Loops through a list of values (or other lists) as extracted from the ActionScript 2.0 file repeating the contents between it and the following TemplateEndRepeat tag for each item in the list
  • TemplateParam: Used for inserting non-ActionScript 2.0 file related values such as the current date or a sequence of numbers incremented with each iteration of a TemplateBeginRepeat loop
  • TemplateBeginFile: Sets a new output name for HTML output generated by AS2Docular (output is handled by the document implementing the AS2Docular class)

Before going into more detail about each of those tags and what they're capable of exactly, you'll need to understand the structure of an ActionScript 2.0 file as interpreted by AS2Docular. The TemplateBeginEditable and TemplateBeginRepeat template tags rely on this structure to properly return a value or loop through the correct list of values when documentation is generated.

When AS2Docular interprets an ActionScript 2.0 file, it reads through finding each /** ... */ block comment and logs it with the line of code that follows into a list called the members list. This list is then subdivided into 5 other lists: doctypes, properties, constructors, methods, and events. Each of these represent the primary "root" lists of an ActionScript 2.0 document and contain content that is relevant to their name (i.e. the properties list contains a list of all the properties documented in the ActionScript 2.0 file). Content within lists is interpreted further into additional lists or specific property values.

  • members: A list of all JavaDoc-commented doctypes, constructors, properties, methods and events within an ActionScript 2.0 file.
  • doctypes: A list of document types associated with the ActionScript 2.0 file. Technically, there should be only one, either a class definition or interface definition.
  • properties: A list of properties within the file.
  • constructors: A list of constructors within the file. There is usually one or none of these.
  • methods: A list of methods within the file.
  • events: A list of events within the file. Events are identified as properties declared with a name starting with "on" followed by a capital letter or number and have a Function data type.

TemplateBeginRepeat tags are used to loop through lists. TemplateBeginRepeat tags can be used within other TemplateBeginRepeat tag blocks to loop through lists defined within those lists. TemplateBeginEditable tags get property values from the current loop within a TemplateBeginRepeat block (a block being between the TemplateBeginRepeat and TemplateEndRepeat tags). Anything within a TemplateBeginEditable block represents a default value if the property referenced doesn't exist or contains an empty value. Each TemplateBeginRepeat and TemplateBeginEditable require their respective closing tags.

Every template tag has their own properties which let you specify which ActionScript property they reference as well as let you set some text values to be used for the generated HTML. These include properties the respective Dreamweaver template tags supports as well as additional properties they do not.

  • TemplateBeginEditable
    • name: (required) the name of the ActionScript property to obtain
    • type: (required in root list loops) specifies whether, in the ActionScript, the comment block or the section of code it references is used to obtain properties from when looping through a primary root list. Additionally, if not within root, it can be used to specify a loop created as though in the context of the document root. Acceptable values are "root", "comment", and "code"
    • prefix: (optional) text to be placed at the beginning of the property value obtained. This is not added if the default value is used
    • suffix: (optional) text to be placed at the end of the property value obtained. This is not added if the default value is used
  • TemplateBeginIf
    • cond: (required) the condition for the if block. This can be used to check for the existence of an ActionScript property or to compare its value with text. When checking for the existence of a property, the property's name is the condition, e.g. cond="description". When checking for a value, the property name and text to compare is used separated by an equals sign (=), e.g. cond="name=getValue". An exclamation point (!) can be used to negate conditions. For example cond="!description" will be true if description does exist and cond="name!=getValue" will be true if name does not equal getValue.
    • type: (required in root list loops) specifies whether, in the ActionScript, the comment block or the section of code it references is used to obtain properties from when looping through a primary root list. Additionally, if not within root, it can be used to specify a loop created as though in the context of the document root. Acceptable values are "root", "comment", and "code"
    • prefix: (optional) text to be placed at the beginning of the property value obtained. This is not added if the default value is used
    • suffix: (optional) text to be placed at the end of the property value obtained. This is not added if the default value is used
    • default: (optional) text to be used if the condition resolves to be false (equivalent to placing text in a TemplateBeginEditable block)
  • TemplateBeginRepeat
    • name: (required) the name of the ActionScript list to loop through
    • type: (required in root list loops) specifies whether, in the ActionScript, the comment block or the section of code it references is used to obtain properties from when looping through a primary root list. Additionally, if not within root, it can be used to specify a loop created as though in the context of the document root. Acceptable values are "root", "comment", and "code"
    • prefix: (optional) text to be placed at the beginning of the loop. This is not added if the default value is used
    • separator: (optional) text to be placed between each item looped through. This is not added if the default value is used
    • suffix: (optional) text to be placed at the end of the loop. This is not added if the default value is used
    • default: (optional) text to be used if the list referenced is empty or does not exist (equivalent to placing text in a TemplateBeginEditable block)
  • TemplateParam
    • name: (required) the name of the type of parameter to use. Acceptable values are "date", "counter", and "cycle"
    • type: (required for some parameters) determines whether or not the parameter is run local to the loop or globally. Acceptable values are "local", and "global"
    • value: (required) text that defines a parameters behavior
  • TemplateBeginFile
    • (none)

Each property value must be surrounded in quotes and can consist of any text except HTML comments (<!-- -->). Quotes and only quotes within property values must be escaped, e.g. prefix="<div class=\"list\">".

When starting with an HTML template, to start extracting ActionScript values, you normally start with a TemplateBeginRepeat tag since all values are contained within any or all of the primary root lists. Which loop is specified in the TemplateBeginRepeat tag's name property. For primary root lists, this is the only required property. Within a TemplateBeginRepeat block that is looping through a primary root list, you can specify additional TemplateBeginRepeat or TemplateBeginEditable tags for more loops or property extraction. For tags directly within a primary root list loop, a type property is required to specify "code" or "comment" to determine which part of the current list object you wish to use, that which makes up the comment or that which makes up the code.

Because AS2Docular allows for any block comment @ tag to be specified, in order to prevent confliction between properties defined in the comment and those used to represent aspects of the code they reference, each comment and code are extracted into separate blocks of reference. These are specified with the type template tag. Once this type has been specified for a repeat tag, nested loops within that tag do not specify type. The only time type would be used within those is if a repeat loop is needed to start back in the document root using a type value of root. This lets you loop through primary root lists while within other nested lists (if, for example, you need to get the class name within a loop).

The following maps out how an ActionScript block (comment and code) is interpreted:

root (document):

name="members" &                  // <- members are all comment-code blocks retrieved
name="doctypes" &                 // each following primary global list consists of individual
name="properties" &               // blocks copied from the members list
name="constructors" &
name="methods" &
name="events"
 |
 +- type="comment"                // <- user defined properties in /** ... */ block comment
 |   |
 |   +- name="description"        // <- first untagged group of text and any additional named description
 |   |   |
 |   |   +- name="text"
 |   |
 |   +- name="user-specified"     // <- any user-specified tag and respective text
 |   |   |
 |   |   +- name="text"
 |   |
 |   +- name="param"              // <- parameters
 |   |   |
 |   |   +- name="name"           // <- parameter name (first word in following text)
 |   |   +- name="type"           // <- parameter data type (as provided in code)
 |   |   +- name="description"    // <- parameter description (text following name)
 |   |   +- name="text"
 |   |
 |   +- name="return"             // <- return value
 |   |   |
 |   |   +- name="type"           // <- return data type (as provided in code (i.e. returntype))
 |   |   +- name="text"
 |   |
 |   +- name="see"                // <- see - references another member
 |       |
 |       +- name="id"             // <- id matching the id of the member the name references
 |       +- name="name"           // <- name of the matching member
 |       +- name="definition"     // <- definition of the matching member
 |       +- name="text"
 |
 +- type="code"                   // <- properties extracted from line of code following comment
     |
     +- name="kind"               // <- code identifier: "class", "interface", "var", or "function"
     +- name="list"               // <- the name of the primary global list the block belongs to
     +- name="definition"         // <- full line including extends and implements
     +- name="intrinsic"          // <- "intrinsic" if code identified as intrinsic
     +- name="dynamic"            // <- "dynamic" if code identified as dynamic
     +- name="access"             // <- provides "public" or "private" depending on member access
     +- name="static"             // <- "static" if code identified as static
     +- name="extends"            // <- (doctypes only) object the document extends if any
     |   |
     |   +- name="name"           // <- base name of the superclass
     |   +- name="path"           // <- package path directories, not including name
     |   |   |
     |   |   +- name="text"
     |   |
     |   +- name="text"
     |
     +- name="implements"         // <- (doctypes only) interfaces that the document implements
     |   |
     |   +- name="name"           // <- base name of the interface
     |   +- name="path"           // <- package path directories, not including name
     |   |   |
     |   |   +- name="text"
     |   |
     |   +- name="text"
     |
     +- name="type"               // <- data type
     +- name="param"              // <- (methods and constructors) parameters
     |   |
     |   +- name="name"           // <- parameter name
     |   +- name="type"           // <- parameter data type
     |   +- name="text"
     |
     +- name="value"              // <- (properties only) default value if assigned
     +- name="returntype"         // <- return value's data type (same as type if property var)
     +- name="id"                 // <- unique numeric id representing order in file
     +- name="path"               // <- package path directories, not including name
     |   |
     |   +- name="text"
     |
     +- name="name"               // <- item name, not including package (path)

Each branch represents a value that can be looped with TemplateBeginRepeat. Those without branching are direct values which can be obtained with TemplateBeginEditable. Be aware that the branching for type (comment and code) is placed in the same tag that the subsequent name property is specified. So going through comment descriptions with a TemplateBeginRepeat within a root methods loop uses only one TemplateBeginRepeat tag with both type and name specified. The methods loop itself doesn't require a type, nor does any loop used within the descriptions loop.

Notice that each comment property (/list) branches out at least once, even if only containing one text property (a text property simply represents the direct text associated with the named property). This is because you can have the same @ tag repeated multiple times as seen with @param and @see in a previous example. Each comment property is assumed to be a list. Code properties, on the other hand, are more specific and may be lists or simply property values. If a TemplateBeginEditable is used on a list, the last value within that list is returned.

HTML templates use the TemplateParam tag to generate text not specific to the ActionScript 2.0 file being interpreted. There are 3 variations: date, counter, and cycle which are specified in the name property of a TemplateParam tag.

  • date: Provides the current date
  • counter: Creates a number that can be incremented, often used to number items in a loop
  • cycle: Creates a cycle of values that repeat themselves when looped

Additional properties, type and value, define their behavior.

  • date
    • value: Date format as used in the PHP date() function.
  • counter
    • value: A starting value for the counter (e.g. "set 1") or the increment at which the counter increases (e.g. "+1")
    • type: Determines whether or not the counter continues within only the current loop (local) or within any loop (global). Acceptable values are "local" and "global"
  • cycle
    • value: A pipe ("|") delimited list of strings that will be used in a cycle. When the last string in a loop is reached, the next value returned will be the first
    • type: Determines whether or not the cycle continues within only the current loop (local) or within any loop (global). Acceptable values are "local" and "global"

That basically covers it. The following examples will better illustrate how HTML templates generate content from an interpreted ActionScript 2.0 file.

The first example will cover basic usage of TemplateBeginRepeat and TemplateBeginEditable.

  1. ActionScript File: Tree.as
    The Tree class is a simple class with 3 properties: bark, branches, and roots. The class definition and 2 properties are commented with /** ... */ block commenting.
     
  2. Template File: template1.html (txt)
    The HTML template used for this class consists of two TemplateBeginRepeat tags, one for looping through doctypes and the other for properties. In each are two TemplateBeginEditable tags, one for name and the other for description. Notice that, since each are in a root loop, a type property is provided to specify whether values from the comments or code are being used. The text within the TemplateBeginEditable tags represent default values - what to use if the property is empty or doesn't exist. Typically we shouldn't see this in the final documentation if the class is commented as it should be.
     
  3. Resulting Documentation: tree.html
    You can see the comment replacements in the resulting generated documentation. Though there are 3 properties for the Tree class, notice that only 2 are listed. This is because the roots property wasn't provided with a preceding block comment so AS2Docular ignored it. As you can see, all property names and descriptions were properly found so none of the default text within the TemplateBeginEditable tags was used.

The next example is an ActionScript 2.0 interface file. The template being used will make use of nested TemplateBeginRepeat tags as well as some TemplateBeginIf tags to A) help distinguish classes from interfaces and B) only list parameters for methods if they exist. Comment @ tags will also be used to extract more information about methods defined within the interface.

  1. ActionScript File: FightingStyle.as
    FightingStyle is a basic interface with 2 methods. The interface itself along with each method is commented so nothing will be missed in the template. Each method has @ tags helping describe their characteristics.
     
  2. Template File: template2.html (txt)
    The HTML template consists of two parts, one for the doctype(s) and one for the methods. For the doctype, a TemplateBeginRepeat is used to cycle through the doctypes - the only doctype. Within that loop is a TemplateBeginIf tag. It's condition is cond="kind=interface" which checks to see if this doctype is an interface. If so, the interface's name is displayed as "Interface (name)". Following that TemplateBeginIf is another TemplateBeginIf which checks the kind to be a class. If a class, the message "This template does not support classes." is displayed.

    Following the doctypes loop is a TemplateBeginIf checking for methods. If methods exist, they are looped through. Following the name and description for each method is another TemplateBeginIf checking for parameters. If they exist, a TemplateBeginRepeat is used to loop through and display them as well.
     
  3. Resulting Documentation: fightingstyle.html
    One thing you'll probably notice right away with the resulting documentation is the excess white space. If you want to avoid this, you'll have to remove the white space between template tags. This can make for an ugly (and horizontally lengthy) template file but is sometimes needed for appropriate formatting. Also notice that the description for the headbutt method says only "Massive blows with the forehead" and not "Causes this fighter to headbutt opponent". This is because description, like every other comment property, is a list. When a list is retrieved with TemplateBeginEditable, the last value in that list is returned. Since the first un-tagged comment line is contained under the description property, it becomes the first of two, the other being that associated with the explicit @description tag. This is the last tag in the list so its value is returned. If all descriptions are desired, a TemplateBeginRepeat would be needed to loop through and display each.

    Everything else works out as it should. The document is correctly identified as an interface and parameters for kick and only kick are displayed as it was the only method that had them all thanks to TemplateBeginIf tags.

The last example covers some uses of TemplateParam tags and how @see links can be created using see's id property.

  1. ActionScript File: Cursor.as
    This Cursor class resides in the com.senocular package and extends MovieClip. It has a few properties and methods, all commented. One method, onFade represents an event. AS2Docular will recognize it as being one as it begins with "on" followed by a capital letter and has Void as a return type. Any method with those qualities are seen as events.
     
  2. Template File: template3.html (txt)
    Things to note in this template file are the use of TemplateParam tags and how id properties are used in HTML anchors. Each of the three TemplateParam tags are used. A counter tag, which increments itself by 1 every time its used, generates numbers for each property, method and event listed. Because it is of the type global, the value doesn't reset is kept for each list in which its used. The cycle TemplateParam tag, however, is defined with a type of local. It resets itself for each list starting again by its first value. If it were global, the background colors wouldn't start back at blue for the beginning of each list. At the bottom of the page, the date is posted using the date TemplateParam tag.

    Each property, method, and event are preceded by a named anchor tag. This allows for links to be followed to their location within the page - links such as those created with @see tags. Each list references the see properties within them. If they exist, links are created that go to #[id] which reference their respective named anchor tags. Member names could also be used as links
     
  3. Resulting Documentation: Cursor.html
    I'm sure it's everything you had hoped it would be.
[index]

Sample Template Style References

[index]

Tips and Tricks

  • Keep in mind that white space matters when using HTML template comment (<!-- -->) tags. This is especially important in something such as a comma separated list generated with a TemplateBeginRepeat. If your TemplateEndRepeat is not directly after the content of the block, a space may be seen in the resulting HTML.
  • Though some template tags have default properties where you can specify default text to be used (if the property doesn't exist or consists of an empty value), it would be a good idea to, instead, use TemplateBeginIf tags to first check for the existence of the property. The advantage of TemplateBeginIf tags is that you can use other tags within a TemplateBeginIf block, unlike that with the default property. Simply use cond="!propertyname" and include your "default" values within the TemplateBeginIf tag block.
  • It may be useful to create your own HTML templates for your files so that you can easily change their style. Current samples use inline styles. With a custom HTML template, you can use a linked style sheet and easily edit that style sheet to change the look and feel of all your documentation. If you do not feel comfortable with making your own HTML templates, you can always copy one used as a sample and edit its style information to suit your needs.
  • AS2Docular recognizes the next line of text (not including blank line) following a /** ... */ block comment as the code relating to that comment, even if the following line is, itself, a comment (single-line // comment). If you "comment-out" a property definition that is preceded by a block comment, it will be picked up by AS2Docular as though it were uncommented. This can work against you if you wish for that not to happen. However, it can also work for you in that it allows you to create documentation for elements within the ActionScript 2.0 file that won't actually be interpreted by Flash if commented. You may want to use commented lines for describing multiple constructors, getter/setter definitions, definitions that are inherited, or for those that exist in some other way that don't require a declaration/definition.
  • Making your own lists. Keep in mind that all blocks interpreted by AS2Docular are categorized into their own respective lists such as methods and properties, but also are all retained within the members list. You can effectively create your own lists by defining a custom @ tag in your code that specifies a category or custom list name for that block. Then, all you need to do in the HTML template is repeat through the root members list and use a TemplateBeginIf to check for the value of that @ tag. If it matches the category or custom list you specified, the repeat loop will only loop through those associated with that tag
[index]

Limitations

Despite the formatting possibilities provided with AS2Docular, there are, as with most things, limitations:

  • An active connection to the internet is needed to use AS2Docular as it is an online application. AS2Docular is written in PHP which requires a PHP-enabled web server to run. If you have your own local web server and would like a copy of AS2Docular for personal use, I will make that available after a 1.0 release.
  • AS2Docular also only parses a single file at a time not taking into consideration other files such as those that the current class might inherit from (as JavaDoc does to show complete inheritance hierarchy).
  • Inline tags such as {@link} are not supported.
  • JavaDoc %I% and %G% for @version are not supported.
  • AS2Docular does not recognize paths for objects whose paths are imported with the import command
  • Possibly many other things I cannot think of at the moment.
[index]

Version History

  • 0.9.6:
    • Updated to a new tabbed interface
  • 0.9.5:
    • Removed the type applied to the default value of TemplateBeginEditable blocks if that TemplateBeginEditable specified one. Before this change, you couldn't access comment properties within a TemplateBeginEditable default block if the TemplateBeginEditable type was specified as being code.
    • Included preferences for the AS2Docular class
    • Included custom parameters (TemplateParam type="custom") for the AS2Docular class
    • Fixed a typo causing the date TemplateParam to always result in 0
  • 0.9.4:
    • Added support for a <!-- TemplateBeginFile --><!-- TemplateEndFile --> tag (this is not a standard Dreamweaver tag). Content within a TemplateBeginFile block is resolved as a filename. Whenever a filename is defined through TemplateBeginFile, all following template translation is output associated with that name. This also meant changing the output of ASDocular->translate() from a sting to an array of an unnamed buffer and an array of TemplateBeginFile-named files and their respective outputs. Note that the saving of a file is not handled by ASDocular; it simply generates HTML strings from ActionScript and HTML templates. File saving would be left to the PHP document implementing the ASDocular class
    • Fixed unmatched TemplateEndIf warning message which incorrectly identified itself as an unmatched TemplateEndEditable
    • Added list code property which represents the root list the code item belongs to (can be used when cycling through members to distinguish items)
    • Changed behavior that removed preceding asterisks (*) in a comment block to only remove up to 1 character of white space following an asterisk. This makes it easier to include preformatted text within a comment block whose lines are all preceded by asterisks
  • 0.9.3:
    • Fixed bug causing erroneous asterisks (*) to be left in a comment definition when not followed by text
    • Allowed @see tags to recognize members not only through name, but also definition. Definition was also included as a property of see
  • 0.9.2:
    • Added type property to @param and @return comment tag properties. Comment params now have the properties name, description, type and text; and returns now have type and text. Type values are those extracted from the comment's relating code line
    • Included code properties for interface, dynamic, static, access (public or private), and value
    • Fixed pattern matching bug where keywords surrounded by "$" in definition names would be incorrectly recognized as the valid keywords applying to that definition, e.g. class my$dynamic$Class { ... } would be recognized as being dynamic
    • Included support for <!-- TemplateBeginIf --><!-- TemplateEndIf --> template tag blocks which support checking for whether or not a property or list exists and for comparing property values with text
    • Changed event recognition from using variables to using methods.
  • 0.9.1:
    • Public Release
    • Provided condition where a primary root list name property can be retrieved using a TemplateBeginEditable, skipping the need for TemplateBeginRepeat (only in the root scope)
    • Set order of primary root list name and inner property text properties to be last in properties available
    • Included support for extends and implements, parsing those objects and interfaces within the doctype definition
    • Returned event recognition to be based on a var with the "on" + [A-Z0-9] pattern and a Function data type in favor of the event keyword.
[index]