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 {
...
}
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 :<xsl:attribute name="src">
<xsl:value-of select="$baseRef"/>
<xsl:text>asdoc.js </xsl:text>
</xsl:attribute>
</script>
<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>
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>
*/