ZenDoc is a simple, free, (primarily) web-based application written in PHP used to generate customizable HTML documentation for Flash ActionScript 2.0 and ActionScript 3.0 source files. Like other tools of its kind, it uses Javadoc-style comments within source code to decide the content of the documentation generated. For more on correctly commenting source files for ZenDoc, see Commenting Source Files for ZenDoc. Note that ZenDoc works using a "consider only what's commented" approach to source code parsing meaning any code without Javadoc comments is ignored.
ZenDoc also gives you to control over the documentation content by way of HTML templates. These templates give you control over the style and layout of the documentation generated from source files. They follow conventions similar to those found in Dreamweaver making them easy to create and customize on your own. Learn more about templates in the ZenDoc Template Format section.
Though ZenDoc can document many files at one time, each file is documented individually, so it works best when documenting single classes rather than entire packages or collections of classes which relate to each other. Documenting multiple files (local) requires access to the file system in which ZenDoc is installed. If you do not have access, you can still use ZenDoc's external documentation feature but would be limited to documenting one file at a time.
You can start using ZenDoc right now by going to http://www.zendoc.org/zendoc/ and accessing the web interface there. You also have the option of downloading ZenDoc to use on your own (see Installation).
[index]ZenDoc is written in PHP. it requires an installation of PHP within the environment you are working to function. If you do not have PHP installed locally on your personal desktop or laptop computer, nor have the desire to do so, you may upload your copy of ZenDoc to your web hosting provider and using it there (assuming PHP is supported).
As a web-based application, ZenDoc web interface also requires a web server like Apache and a JavaScript-enabled Browser like Firefox (ZenDoc was originally written and tested on Windows XP Pro running Apache 2 with PHP 4.3.8 using Firefox 1.0.4+). If only using ZenDoc through the command line, you will only need to have PHP installed.
To download the latest version of ZenDoc, please visit www.zendoc.org.
To install, unzip the download into the desired location placing the zendoc folder in the directory you wish to run ZenDoc. When using the web interface, this should be in a folder on your web server.
To uninstall ZenDoc, all you need to do is delete the zendoc folder.
[index]ZenDoc can be used two ways, through the PHP Command Line Interface (CLI) and through a web interface. More than likely you will want to use ZenDoc through the web interface as it provides the most in terms of flexibility and options.
Before using ZenDoc in any context, you'll probably want to set options defined in the zendoc.ini file. This file is located in the root ZenDoc folder. It contains options accessed by ZenDoc when it runs for both the command line and the web interface. Many of these options can also be changed through the ZenDoc web interface when using ZenDoc with your browser. The values within the ini file represent the default values for the web interface.
The script to use for ZenDoc with PHP's CLI is zendoc.php located in the bin folder. The only arguments it accepts are the source files you wish to have documented. All options are decided by zendoc.ini. Documentation created with zendoc.php is saved in the same directory as the source file it documents.
A Windows batch file template (ZenDoc.bat) is also provided in the bin directory to make working with zendoc.php a little more easy for Windows users. Before using ZenDoc.bat, you must open it in a text editor and edit the phpclipath and zendocfilepath variables as they relate to your system. Once that is done, you can just drag and drop source files onto the ZenDoc.bat file to instantly create documentation for them. Using this batch file you can also create a user tool to run ZenDoc through editors like SE|PY.
To run ZenDoc using its web interface, just navigate to the ZenDoc folder on your web server (index.php) using your browser. An interface for the ZenDoc application will appear.
The ZenDoc interface is divided into three sections accessible through tabs; Local Files, External Files, and Options. The Local Files section show files located on the server running ZenDoc and are best used with your own personal copy of ZenDoc. The External Files section is more appropriate for using ZenDoc on a server you do not have access to, or for just quickly generating documentation for one or two files not within the local files listed for ZenDoc. The final section, Options, provides a list of options for ZenDoc and its components. A link to the ZenDoc documentation is provided to the right of the tabs.
The Local Files section lists out all .as source files in the specified directory (except folders that start with an underscore like _notes). Copy any and all .as files you wish to generate documentation for into this directory. You can click on the name of any listed file to view it. If ZenDoc recognizes that documentation already exists for a file a (doc) link will also be provided next to the file allowing you to view it as well.
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 ZenDoc, see Commenting Source Files for ZenDoc. If a file that is not recognized as a source file is selected, ZenDoc will skip that file when attempting to generate documentation.
Once files are selected, a 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 ZenDoc install directory. By default, 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 ZenDoc Template Format section.
Once all of your selections have been made, click on the Document Local button at the bottom of the interface to generate HTML documentation for all selected source files in the source file listing. The interface will reload with the inclusion of an output window located below the file listing indicating the results of the operation. There you will see what documents were generated and any errors if present.
The External Files section provides basic ZenDoc functionality to files not located on the machine that ZenDoc is running. Both external source files and template files can be used here, either uploaded or provided as text. Those templates available to ZenDoc are also available for use here, though the local source files are not.
The Write text fields for either the ActionScript Source File or the Template Source File allow you to write in or copy and paste text for your source or template. If you wish to use this text, make sure the respective radio button is selected for that field. Additionally, you can choose to select a file on your hard drive using the option to Upload.
Clicking on the Document External button will generate documentation in a new window. You may save this documentation using your browser's save option. If there was an error, an error message will be displayed instead of the documentation.
The Ignore TemplateBeginFile tags option is automatically considered checked when documenting external files as documentation is provided in a new window. Similarly, Client options involving saving files do not apply to external documentation.
The options tab provides many of the options available to ZenDoc. Learn more about what options are available in the ZenDoc Options section. Most of these options will be applied to the next documentation operation making the use of the Apply option unnecessary. However, the Local Files tab uses the output file extension to recognize which files have documentation available to them. If you change that option, you will need to click Apply to update the files listing with documentation links associated with that extension.
[index]There are a number of options available for ZenDoc, each relating to a different part of the application. These can be set within the an ini file, or the ZenDoc HTML interface. Those set in the interface override those within the ini file unless the ini file locks the property. To lock a property, define a new property in the ini file with the name lock_ plus the name of the property you wish locked with a value of true.
These options relate to the ZenDoc client.
These options relate to the ZenDoc translator .
These options relate to the ZenDoc ActionScript parser.
Options specific to external documentation are available in the External Files tab. They are as follows:
The ZenDoc ini file also allows for some options not available in the interface. They are as follows:
[index]
In order for ZenDoc to correctly generate documentation for your ActionScript 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 ZenDoc 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 property:
/**
* The number of frames to be used in animating the selection
*/
public var frames:Number;
When commenting code that contains meta tags, put the comments above the meta tags.
/**
* The number of frames to be used in animating the selection
*/
[MetaTag(value)]
public var frames:Number;
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 ZenDoc, there is no set of specific tags that you are limited to using. All tags, regardless of tag name (aside from @param, @throws, @return and @see), are treated equally. Their inclusion into the final documentation generated by ZenDoc is dependant on the HTML template used when that documentation is created. That means you can use a tag called @best_tag_ever and include its contents into your generated documentation so long as the template you use was built to support it.
The @param, @throws, @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 ZenDoc 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 ZenDoc 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 @throws tag is treated much like @param, only it consists of a first word that is the error type of the error thrown followed by its description. ZenDoc does not include anything from the source code to the values supplied with @throws.
The @return tag in the comment is like most other tags, just having a description. However, as with @param and 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. ZenDoc 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
* @throws IOException If an input or output exception occurred
* @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 ZenDoc 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 that is important to understand is that ZenDoc 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). This was done to keep ZenDoc simple and efficient.
HTML templates are the most complicated aspect of ZenDoc, yet they are also what makes ZenDoc 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 your own custom template.
The HTML templates used by ZenDoc are basic HTML files that define the layout of the documentation generated for a source file. Special Dreamweaver-like template tags within the template are used to determine what content from an ActionScript file is placed where. When the final HTML for the documentation is created, these tags are replaced with their respective values as interpreted by ZenDoc.
The following template tags are used by ZenDoc. Most are similar to commonly used Dreamweaver template tags.
<!-- TemplateBeginEditable name="..." [type="..."] [prefix="..."] [suffix="..."] [default="..."] --> 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 <!-- TemplateEndFile -->
*Properties surrounded by brackets ([]) represent optional properties.
There are actually 2 ways to write template tags, one using HTML comments as seen above with <!-- and -->, and an alternate way using the optional Dreamweaver expression tags @@( and )@@. For example, these tags are equivalent:
<!-- TemplateParam name="global" type="counter" value="+1" --> @@( TemplateParam name='global' type='counter' value='+1' )@@
You would want to use <!-- and --> when writing template tags outside of other HTML tags and use @@( and )@@ when including template tags inside other HTML tags.
Tags are case sensitive and properties must be separated with spaces. Property values can be contained in either single or double quotes. Values within a property must use appropriate character entity replacements.
Here is each tag and its meaning:
TemplateBeginEditable:TemplateBeginIf:TemplateBeginRepeat:TemplateParam:TemplateBeginFile: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 file as interpreted by ZenDoc. 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 ZenDoc interprets an ActionScript 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 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 file). Content within lists is interpreted further into additional lists or specific property values.
members:doctypes:properties:constructors:methods:events: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.
TemplateBeginEditablename:type:prefix:suffix:default:TemplateBeginIfcond:type:prefix:suffix:default:TemplateBeginRepeatname:type:prefix:separator:suffix:default:TemplateParamtype:name:value:TemplateBeginFileWhen 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 ZenDoc 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="methods" & // blocks copied from the members list name="properties" & name="constructors" & name="events" | +- type="comment" // <- user defined properties in /** ... */ block comment | | | +- name="user-specified" // <- any user-specified tag and respective text | | | | | +- name="text" | | | +- name="description" // <- description (usually first untagged group of 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="throws" // <- error method might throw (a.k.a. exception) | | | | | +- name="type" // <- error data type | | +- name="description" // <- error description (text following type) | | +- 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: "package", "class", "var", etc. +- name="list" // <- the name of the primary global list the block belongs to +- name="definition" // <- full line including extends and implements; | | // (will contain multiple definitions for combined get and set) | +- name="text" | +- name="meta" // <- meta tags for the block | | | +- name="text" | +- name="intrinsic" // <- "intrinsic" if code identified as intrinsic +- name="native" // <- "native" if code identified as native +- name="final" // <- "final" if code identified as final +- name="override" // <- "override" if code identified as being an override +- name="get" // <- "get" if code identified as being a getter +- name="set" // <- "set" if code identified as being a setter +- name="dynamic" // <- "dynamic" if code identified as dynamic +- name="access" // <- provides "public", "private", etc. or namespace +- 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 first value within that list is returned.
HTML templates use the TemplateParam tag to generate text not specific to the ActionScript file being interpreted. There are 3 variations: date, counter, and cycle which are specified in the name property of a TemplateParam tag.
date:counter:cycle:Additional properties, type and value, define their behavior.
datevalue:countervalue:type:cyclevalue:type:That basically covers it. The following examples will better illustrate how HTML templates generate content from an interpreted ActionScript file.
[index]The first example will cover basic usage of TemplateBeginRepeat and TemplateBeginEditable.
/** ... */ block commenting.The next example is an ActionScript 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.
The last example covers some uses of TemplateParam tags and how @see links can be created using see's id property.
/** ... */ 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 ZenDoc 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 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.Despite the possibilities with ZenDoc, there are, as with most things, limitations:
* Remember ZenDoc only parses code which has a block /** ... */ comment preceeding it - this includes meta tags.
[index]ZenDoc was conceived and written by Trevor McCauley (www.senocular.com). For the latest version and updates visit www.zendoc.org. Special thanks to Pixelwit.
[index]