How to insert a SWF file in an ASDoc API documentation ?

ASDoc API documentation is well designed for developers but remain difficult to read for others. Some of my co-workers are web designer. They code a bit but they want API to be simple and they want usage examples. In the past days I developed some image filters and effects for them. The resulting API has very few meaning without a real example of code and a way to test it. Thus, I wanted them to be able to access the code examples as well as being able to test the result of each effects, inline, in the ASDoc documentation. Click the image below to see the rendering SWF tester.

Code examples are easy to integrate using the @example and @includeExample (Flex 4), but there is no default way of inserting SWF files directly (as far as I know). In order to insert a SWF file in a generated ASDoc API documentation, one needs to understand the process of generating documentation with ASDoc. On one side there are packages and classes, on the other side ASDoc templates files. Generating documentation consists for the asdoc.exe application of parsing the classes for any special comments and injecting what has been found in the templates. The result is output in a directory and is made of a bunch of HTML, CSS, JavaScript files… The type of special comments the ASDoc process is looking for looks like that :

/**
 * Apply an RGB distortion effect on a DisplayObject
 * 
 * @param target The DisplayObject on which to apply the effect
 */
override public function apply(target : DisplayObject):void{
    ...
}

Special tags starting with an @ can be used in these comments and will be interpreted by the ASDoc process. Fortunately HTML tags can be used as well inside these comments and will be output unchanged. I make use of this feature to insert SWF files inside the documentation.

Step 1 : adding the required JavaScript libraries to the ASDoc templates

Note : in the following section you have to download several components to make it works. I packaged all of them in a zip file. ASDoc templates are located in a Flex SDK sub-directory by default : FLEX_SDK_DIR\asdoc\templates To keep unmodified the original templates you can copy this folder outside the Flex directory. In this case to make the ASDoc process being aware of this change use the command parameter -templates-path ‘path/to/your/new/template_folder’ Full ASDoc documentation is located on Adobe Web site In the template folder locate the file asdoc-util.xsl and in there search for those lines :

<script language="javascript" type="text/javascript">
    <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
        <xsl:text>asdoc.js</xsl:text>
    </xsl:attribute>
</script>

insert the following lines just before the previous ones :

<script language="javascript" type="text/javascript">
   <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
         <xsl:text>jquery.min.js</xsl:text>
    </xsl:attribute>
</script>
<script language="javascript" type="text/javascript">
   <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
         <xsl:text>swfobject.js</xsl:text>
    </xsl:attribute>
</script>
<script language="javascript" type="text/javascript">
   <xsl:attribute name="src">
        <xsl:value-of select="$baseRef"/>
         <xsl:text>swf-loader.js</xsl:text>
    </xsl:attribute>
</script>

As you may guess we will use jQuery and SWFObject to achieve our goal. Download jQuery and SWFObject and put the files in the templates directory (rename the files to match the previous lines). From the SWFObject download ZIP file, extracts the expressInstall.swf file in the templates directory as well. The third file is made by myself and will help substitute special HTML tags in the documentation by SWF files. Save the following code in the file templates/swf-loader.js

$(document).ready(function(){
    var idBase = "swfLoader";
    var idNum = 0;
    var width, height;
    var params = {
        quality: "high",
        scale: "noscale",
        allowscriptaccess: "always",
        bgcolor: "#FFFFFF"
    };
    var flashvars = {};

    $("div[src]").each(function(){
        $(this).attr("id",idBase + idNum);
        width = $(this).attr('width') || "100%";
        height = $(this).attr('height') || "100%";
        
        var flasvarsString = $(this).attr("flashvars");
        var flashvarsArray = flasvarsString.split("&");
        for ( var i = 0; i < flashvarsArray.length; i++) {
            var flasvar = flashvarsArray[i].split(":");
            flashvars[flasvar[0]] = flasvar[1];
        }
        swfobject.embedSWF(
                $(this).attr("src"), 
                idBase + idNum, 
                width, 
                height, 
                "10.0.0", 
                "expressInstall.swf", 
                flashvars, 
                params, 
                {}
        );
    
        idNum++;
    });
});

Step 2 : adding special HTML Tag in ASDoc classes comments

Now that the files are in place it’s possible to add special HTML tags in comments to insert SWF files :

/**
 * Creates an RGB distortion effect (Timed effect).
 * <div src='../../../swf/effectTester.swf' 
 *   width='780px' height='550px' flashvars='form:mosaicForm'></div>
 */

The div tag will be replaced by the SWF files located at ‘../../../swf/effectTester.swf’ passing width, height and flashvars parameters. Flashvars must be of the following form : var1:value1&var2:value2&var3:value3.

Step 3 : where to put the SWF files

Put the SWF files in the doc_output_directory/swf.