JavaScriptXmlDoc 1.1 Documentation

JavaScriptXmlDoc is a documentation generator fo JavaScript libraries written in Java. It reads a xml file containing the documentation structure. It was originally created to build the JavaScripTools documentation. In fact, the most complete example I could provide is it :-) Download the latest JavaScripTools and check out the javascriptools-doc.xml, or view it on SourceForge's online cvs viewer.

Currently, the following elements can be documented:

Project: Description of a whole project, wich is contained by one or more .js files.
Script: A .js file, containing general information and dependencies on other scripts.
Constant: A constant.
Top-Level Function: A function not associated with any class.
Class: A "class". On JavaScript, classes are functions wich are instantiated using the "new" operator.
- Constructor: Arguments wich are passed to class construction. Many times, constructor arguments are also class properties, so, arguments may be also specified as properties.
- Property: A class property.
- Method: A class method.

You can run JavaScriptXmlDoc from the command line or using an ant task.

Running from Ant: Follow this example:

    <taskdef name="jsxmldoc" classname="org.javascriptxmldoc.ant.JavaScriptXmlDocTask">
        <classpath>
            <fileset dir="PATH_TO_JSXMLDOC_DIR" includes="**/*.jar"/>
        </classpath>
    </taskdef>
    <jsxmldoc source="PATH_TO_XML_FILE" dest="DESTINATION_DIRECTORY"/>

Aditionally, you can override the following project attributes: title, name, version and author.

Running from command line: Go to the directory <JSXMLDOC_HOME>/bin, or set the <JSXMLDOC_HOME> environment variable property, and run the jsxmldoc.bat (windows) or jsxmldoc.sh (linux), passing the following arguments:

Option Short Description

--file -f The XML file. May be an absolute path or relative to the current path or to a directory in the class path. Mandatory.

--dest -d The destination folder. May be an absolute path or relative to the current path. Mandatory.

--encoding -e The character encoding. Defaults to ISO-8859-1. Optional.

--template -t The folder containing the Velocity templates. May be an absolute path or relative to the current path. Defaults to 'template' on the class path. Optional.

--help -h Displays the command help.

Option	Short	Description
--file	-f	The XML file. May be an absolute path or relative to the current path or to a directory in the class path. Mandatory.
--dest	-d	The destination folder. May be an absolute path or relative to the current path. Mandatory.
--encoding	-e	The character encoding. Defaults to ISO-8859-1. Optional.
--template	-t	The folder containing the Velocity templates. May be an absolute path or relative to the current path. Defaults to 'template' on the class path. Optional.
--help	-h	Displays the command help.

The latest release can be found here.

jsxmldoc.sourceforge.net

Creating the Documentation XML File

The documentation xml file must declare the following document type:

<!DOCTYPE javascriptdoc PUBLIC
    "-//JavaScriptXmlDoc "
    "http://jsxmldoc.sourceforge.net/javascriptdoc.dtd">

These are the allowed tags:

javascriptdoc

Is the root document tag. It describes an entire project, contained of many scripts.

Attribute	Description	Required
name	The project name	true
title	The documentation title	false
description	The project description. May be replaced by a nested description tag	false

Children: description (optional), script (one or more)

script

Represent a script file (.js), wich declares constants, functions and classes.

Attribute	Description	Required
name	The script name	true
description	The script description. May be replaced by a nested description tag	false

Children: description (optional), dependencies (optional), constants (optional), functions (optional), classes (optional)

dependencies

A container tag for dependency declaration.

Children: dependency (one or more)

dependency

Declares a script dependency - another script that must be imported before this one.

Attribute	Description	Required
script	The script name	true

constants

A container tag for constant declaration.

Children: group (one or more)

constant

Represent a constant.

Attribute	Description	Required
name	The constant name	true
description	The constant description. May be replaced by a nested description tag	false

Children: description (optional), dependencies (optional), constants (optional), functions (optional), classes (optional)

functions

A container tag for top-level function declaration.

Children: group (one or more)

function

Represent a top-level function, that is, functions not associated with classes.

Attribute	Description	Required
name	The function name	true
return	What the function returns (when there is a return value)	false
description	The function description. May be replaced by a nested description tag	false

Children: description (optional), argument (zero or more)

classes

A container tag for class declaration.

Children: group (one or more)

class

Represent a class, that is, functions wich are instantiated using the "new" operator.

Attribute	Description	Required
name	The class name	true
extends	Indicates the base class, that is, wich class this one extends	false
description	The class description. May be replaced by a nested description tag	false

Children: description (optional), example (optional), constructor (optional), methods (optional), properties (optional)

example

A tag containing, on it's body, a class usage example.

constructor

A container tag for a class constructor arguments declaration.

Children: argument (one or more)

methods

A container tag for a class method declaration.

Children: group (one or more)

method

Represent a class method, that is a function associated with that class.

Attribute	Description	Required
name	The method name	true
return	What the method returns (when there is a return value)	false
description	The method description. May be replaced by a nested description tag	false

Children: description (optional), argument (zero or more)

properties

A container tag for a class property declaration.

Children: group (one or more)

property

Represent a class property, that is a variable associated with that class. It may declare nested enum tags, indicating possible enumerated values expected for the property.

Attribute	Description	Required
name	The method name	true
type	The expected property type	false
default	The property default value, that is, the assume value when it's not explicitly changed	false
description	The property description. May be replaced by a nested description tag	false

Children: description (optional), enum (zero or more)

group

Groups nested elements together. Used on constants, functions, classes, methods and properties.

Attribute	Description	Required
name	The group name. When not informed, a "default" group is assumed.	false
description	The group description. May be replaced by a nested description tag	false

Children: description (optional) and one or more of the following: constant, function, class, method or property

argument

Represents a function, method or constructor argument. It may declare nested enum tags, indicating possible enumerated values expected for the argument.

Attribute	Description	Required
name	The argument name.	true
type	The expected argument type.	false
default	The default value, when the argument is not explicitly informed.	false
propertyGroup	Only for constructor arguments. When the constructor argument is also a property, the group name for that property, so there's no need to explicitly declare it.	false
description	The argument description. May be replaced by a nested description tag	false

Children: description (optional), enum (zero or more)

enum

Represents an enumerated value to a property or argument.

Attribute	Description	Required
const	The constant name or value, representing a possible value	true
description	The argument description. May be replaced by a nested description tag	false

Children: description (optional)

description

An element description.