specific asdoc for Redtamarin

Our ActionScript 3.0 source code can be documented at the same time

• for native definitions
• for the Flash Player
• for AIR
• for Redshell
• for Windows
• for Macintosh
• for Linux
• for both Linux and Macintosh

Here some templates to help you either contribute to the Redtamarin documentation or write your own documentation for your libraries.

The Different Player Version

The asdoc tag @playerversion is extremely important, it's what will allow you to communicate where your code can run.

code	version	example
Flash	9	Flash Player 9
AIR	1.0	AIR 1.0
AVM	0.4	RedTamarin 0.4
POSIX	+	POSIX only
WIN	+	Windows only
MAC	+	Macintosh only
NIX	+	Linux only

Basic code meant to run almost everywhere

/**
 * @langversion 3.0
 * @playerversion Flash 9
 */

Yes, Flash Player 9 is our bare minimum, it should also work with AIR and with Redtamarin. But be careful, when it come to documenting the Flash API, even if tagged @playerversion Flash 9, the code could not be available or running in Redtamarin.

AIR only

/**
 * @langversion 3.0
 * @playerversion AIR 1.0
 */

The minimum for AIR specific code, in general the version indicate when the feature got introduced. Same warning as before, the code could not be compatible with Redtamarin at all.
The HTML will show a specific AIR icon for such documentation.

Redtamarin only

/**
 * @langversion 3.0
 * @playerversion AVM 0.4
 */

Specific code available to Redtamarin and not available to the Flash player or AIR.
The HTML will show a specific Redtamarin icon for such documentation.

Mixed runtimes

/**
 * @langversion 3.0
 * @playerversion Flash 11
 * @playerversion AIR 3.0
 */

The functionality is available since Flash Player 11 and since AIR 3.0

Mixed platforms

/**
 * @langversion 3.0
 * @playerversion AVM 0.4
 * @playerversion POSIX +
 */

Available only for Redtamarin Linux and Macintosh, in general a POSIX feature that Windows does not have.

/**
 * @langversion 3.0
 * @playerversion AVM 0.4
 * @playerversion WIN +
 */

Available only for Redtamarin Windows.

/**
 * @langversion 3.0
 * @playerversion AVM 0.4
 * @playerversion MAC +
 */

Available only for Redtamarin Macintosh.

/**
 * @langversion 3.0
 * @playerversion AVM 0.4
 * @playerversion NIX +
 */

Available only for Redtamarin Linux.

The Strict Minimum

/**
 * One line description of the functionality.
 * 
 * @langversion 3.0
 * @playerversion AVM 0.4
 */

If you want to contribute documentation to Redtamarin, that's the minimum we ask

• one line description of what it does
• always use the tag @langversion 3.0
• use at least one tag @playerversion

Now depending on where you want to contribute documentation we may ask for more.

The Strict Minimum for the C Library

/**
 * One line description of the functionality.
 * 
 * <p>
 * Detailed paragraph of what it does.
 * </p>
 * 
 * @example Usage
 * <listing>
 * // few line of examples
 * 
 * // with inline comments
 * 
 * </listing>
 * 
 * @param name description
 * @param name description
 * @return description
 * 
 * @throws C.errno.CError EAGAIN description
 * @throws C.errno.CError EBADF description
 * @throws C.errno.CError EINVAL description
 * 
 * @langversion 3.0
 * @playerversion AVM 0.4
 * 
 * @see http://pubs.opengroup.org/onlinepubs/9699919799/functions/NAME.html
 */

For the C libraries we ask a bit more

• at least one paragraph to give more details and context
• at least one usage example
• all parameters need to be documented
• return value need to be documented
• all throw errors have to be documented
• at least one link towards a C or C++ reference documentation
• if the function is not standard mark it with @see NON STANDARD EXTENSION

Special Tags

Blocking

/**
 * @see "BLOCKING"
 */

Indicate a blocking function.

Example:

• sleep() in C.unistd
• accept() in C.sys.socket
  by default we use blocking sockets
  if a special settings were to allow non-blocking sockets
  we will then list the blocking functions affected by the change
• etc.

Not Implemented

/**
 * @see "NOT IMPLEMENTED"
 */

Indicate a not implemented functionality,
that we plan to implement later.

Example: printf()

    /**
     * Print formatted output.
     *
     * @langversion 3.0
     * @playerversion AVM 0.4
     * 
     * @see "NOT IMPLEMENTED"
     */
    public function printf( format:String, ... args ):int
    {
        errno.value = ENOSYS;
        return -1;
    }

Not Standard

/**
 * @see "NON STANDARD EXTENSION"
 */

Indicate a non-standard extension to the C "standard" library or POSIX.

Example: fcopy()
a utility function added to C.stdio package
but not part of the C standard library nor POSIX.

Note:
Relative to the Flash Player and/or AIR API
non-standard extensions are marked
by the "monkey head" icon.

No Operation

/**
 * @see "NO OPERATION"
 */

Indicate a "NO-OP", a No Operation.
Something you can call or use but which will do nothing, either because
we can't or do not want to implement it.

Example: fork()
a C function that is part of POSIX
but that we do not plan to implement
for a specific reason.

Special Cases

In some cases, asdoc will not "see" some definitions.

The AS3 code is correct, it will work, it just asdoc does not generate the HTML doc for it.

for example:

• variable defined at the package level

package C.something
{
    public var test:String = "TEST";
}

• function defined at the package level

package C.something
{
    public function test():void
    {
        //...
    }
}

• getter/setter defined at the package level

package C.something
{
    public function get hello():String
    {
        //...
    }
}

For those cases, we duplicate the file src/as3/C/something.as
with another one src/as3/C/something_asdoc.as
where we replace most definition by const.

Checklist:

• duplicate the file with ${same_name}_asdoc.as
• in src/redtamarin.as include only
  include "as3/C/something.as";
• in build/targets/documentation.xml include only
  <doc-sources path-element="${basedir}/src/as3/C/something_asdoc.as" />
  prepend it with <!-- DOC -->, eg.
  <!-- DOC --><doc-sources path-element="${basedir}/src/as3/C/something_asdoc.as" />
• for each definitions use the Documentation Signature

    /**
     * Some text.
     * 
     * <p>
     * <b>Documentation Signature:</b>
     * this definition is implemented as <code>CODE SIGNATURE HERE</code>.
     * </p>
     * 
     */

More Documentation

There are some cases where we want/need to document without necessarily having a definition associated to it.

For those cases we will create a stub, for example:
public const MORE_DOC:int = 0;

Checklist:

• create an .as file in the path related to the documentation
  for ex: src/as3/C/test.as
• include it in src/redtamarin_asdoc.as
include "as3/C/test.as";
• include it in build/targets/documentation.xml
<doc-sources path-element="${basedir}/src/as3/C/test.as" />
  prepend it with <!-- DOC -->, eg.
  <!-- DOC --><doc-sources path-element="${basedir}/src/as3/C/test.as" />
• for each definitions use the Documentation Stub

    /**
     * Some text.
     * 
     * <p>
     * <b>Documentation Stub:</b>
     * this definition is here only for documentation purpose.
     * </p>
     * 
     */