Overview

JSXDOC is a program that creates API documentation from JavaScript source files. JSXDOC parses JavaScript syntax and a comment metadata syntax to produce the structured documentation. JavaScript source files that are run through the compiler must conform to the JSXDOC syntax. JSXDOC can export documentation as XML or HTML files.

Syntax

The supported documentation syntax is similar to javadoc syntax. Relevant comment blocks are range comments that begin with /** and are placed immediately before the member that they describe. You can document packages, classes, interfaces, methods, and fields. Methods and fields are defined in the class, interface, or package whose definition most closely precedes it. (It is an error to define a method or field in a location where there is no such class context).

The documentation compiler parses JavaScript to determine what type of member a comment block documents. The member declaration that follows the comment block (or that is specified with the @jsxdoc-definition tag) must match one of the following patterns.

• jsx3.[lang.]Package.definePackage("NAME", ...) Defines a package. The package name is determined from the declaration.
• jsx3.[lang.]Class.defineClass("NAME", SUPER, [IMP1, IMP2, ...], ... ) Defines a class. The class name, superclass, and implemented interfaces are determined from the declaration.
• jsx3.[lang.]Class.defineInterface("NAME", SUPER, ...) Defines an interface. The interface name and super interface are determined from the declaration.
• prototype.NAME = jsx3.[lang.]Method.newAbstract("P1", "P2", ...) ; Defines an abstract method. The method name and parameter order are determined from the declaration.
• prototype.NAME = jsx3.Y(function(...)) Defines an asynchronous method. The method name is determined from the declaration. The method parameters are taken from the @param tags.
• prototype.NAME = function(P1, P2, ...) ... Defines an instance method. The method name and parameter order are determined from the declaration.
• NAME: function(P1, P2, ...) ... Defines an instance method (as in the previous declaration). The method name and parameter order are determined from the declaration.
• x.NAME = function(P1, P2, ...) ... Defines a static method. The method name and parameter order are determined from the declaration.
• prototype.NAME = x; Defines an instance field. The field name is determined from the declaration.
• NAME: x - Defines an instance field (as in the previous declaration). The field name is determined from the declaration.
• x.NAME = x; Defines a static field. The field name is determined from the declaration.

Documentation Blocks

Documentation blocks can begin with a free-form paragraph that describes the member. HTML tags are allowed in this and most other text blocks. HTML entities must be escaped in order to be interpreted as plain text. The type declaration of a field, if documented, must precede its description.

The param, return, and throws tags, and the field description, support optional type information. Types are always documented between curly braces, {}. A type can be any valid JavaScript identifier or package+identifier. A type whose class is included in a compilation will be linked automatically to the definition of that class. The following constructs are also supported, both alone and in most combinations.

• type1 | type2 | ... type1 or type2 or ...
• type1... Variable number of method arguments which should be determined from the JavaScript arguments array.
• pType<type > Parameterized type such as an Array that contains objects of another type.
• pType<type1, type2> Multi-dimensional parameterized type such as a map that contains multiple sets of objects of other types.

Tags

Tags begin on a new line and begin with the @ character. The following tags are supported.

• @public, @package, @protected, @private Sets the access level of the documented member. If a documentation comment exists the default is public, otherwise the default is private.
• @version STRING Documents the version of the member.
• @since STRING Documents the version when the member was introduced.
• @deprecated [STRING] Documents that the member is deprecated and adds an optional description of the deprecation.
• @author STRING Documents the author of the member. Any number of author tags may be documented.
• @param NAME [{TYPE}] STRING Documents a method parameter. Any parameters that are not explicitely documented with this tag are parsed from the definition and included (without type or description) in the compiled documentation.
• @param {TYPE} NAME STRING This is an alternative supported syntax of a method parameter.
• @param-package and @param-private You can use these to set the access level of a particular parameter so that it does not show up in the compiled documentation.
• @return [{TYPE}] STRING Documents the return type of a method and adds a description to the returned object. The type is optional. Method that have no non-empty return statements should not include this tag.
• @throws [{TYPE}] STRING Documents an exception type that a method may throw and the conditions under which it is thrown.
• @final Documents that a method should not be overridden or a class should not be extended. The JavaScript language does not enforce this documentation construct.
• @static Documents a field or member as static even when the member declaration is not understood by the parser to be a static declaration.
• @protected Documents that a method or field should only be used from within the class that defined it or one of that class's subclasses. The JavaScript language does not enforce this documentation construct.
• @abstract Documents that a class is abstract. Methods defined with j sx3.lang.Method.newAbstract() are automatically recognized as abstract. Any class or interface with an abstract member is also automatically recognized as abstract.
• @native Documents that this member is defined by the JavaScript engine or host browser.
• @see STRING Adds a See section to the documentation of this member. There are several supported formats for the STRING argument:
  
  • "TEXT" Inserts a text label.
    
  • <a href="URL">TEXT</a> Inserts an HTML link to URL.
    
  • #LOCAL_FIELD [LABEL] References a field in the same class with optional label LABEL.
    
  • #LOCAL_METHOD() [LABEL] References a method in the same class with optional label LABEL.
    
  • pkg.Class#FIELD [LABEL] References a field in another class, pkg.Class, with optional label LABEL.
    
  • pkg.Class#METHOD() [LABEL] References a method in another class, pkg.Class, with optional label LABEL.
• @jsxdoc-definition JS_DEFINITION In the case that a documentation block cannot appear immediately before the member definition, this tag can be used to specify the member definition. This tag can also be used to tell the compiler what member the comment block describes in the case that members are not defined according to the JavaScript syntax that the compiler expects.
• @jsxdoc-category CLASS In the case that the members of a package, class, or interface are defined across multiple files or sections of files, this tag can be used to indicate that tags following it belong to CLASS but without redefining CLASS in the process.

Example

The following code example declares a JavaScript class, jsx3.util.list, and includes many of the JSXDOC tags.

/**
 * Adapted from <code>jsx3.util.List</code>.
 * <p/>
 * An object-oriented version of the built-in JavaScript <code>Array</code> class.
 * <p/>
 * Note that methods such as <code>indexOf</code> and <code>remove</code> compare objects
 * with the strict equality operators (<code>=h1. </code> and <code>!</code>\). Therefore, for the purposes of this
 * class <code>1</code> and <code>"1"</code> are not equal.
 *
 * @since 3.2
 */
jsx3.Class.defineClass('jsx3.util.List', null, null, function(List, List_prototype) {

  /**
   * {int} A final static field.
   * @final
   */
  List.STATIC_FIELD = 5;

  /**
   * If <code>a</code> is already an instance of this class, this method returns <code>a</code>.
   * If <code>a</code> is an array, this method returns a new List instance backed by <code>a</code>.
* @param a {Array|jsx3.util.List}
* @return {jsx3.util.List}
   * @throws {jsx3.IllegalArgumentException} if <code>a</code> is not a list or array.
   */
  List.staticMethod = function(a) {
    if (a instanceof List) {
      return a;
    } else if (a instanceof Array) {
      return new List(a, true);
    } else {
      throw new jsx3.IllegalArgumentException("a", a);
    }
  };

  /**
   * The instance initializer. Creates a new list.
   * @param a {Array}
   * @param-private bLive {boolean}
   */
  List_prototype.init = function(a, bLive) {
    if (a instanceof Array) {
      this._src = bLive ? a : a.concat();
    } else {
      this._src = ;
    }
  };

  /**
   * @return {int}
   */
  List_prototype.size = function() {
    return this._src.length;
  };

  /**
   * Varargs example.
   * @param o {Object...}
   */
  List_prototype.add = function(o) {
    this._src = this._src.concat(arguments);
  };

  /**
   * Parameterized type example.
   * @return {jsx3.util.List<String>} this list converted to a list of strings.
   */
  List_prototype.toStringList = function() {
    return this.filter(function(e) { return e.toString(); });
  };

  /** @private */
  List._privateMethod = function(a) {
    return a;
  };

});