For documenting the API, special documentation comments (abbreviation: doc comment) are used. These doc comments are similar to javadoc comments, which are used for commenting Java code. Because JavaScript has several basic differences to Java, some of the syntax for the doc comments has been changed.

A doc comment appears right before the structure (class, property, method or constant) it describes. It beginns with /** and ends with */. The rows in between start with a * followed by the text of the particular row. Within this frame there is a description text at the beginning. Afterwards attributes may follow, describing more aspects.

Description texts may also include HTML tags for a better structuring.

An example:

/**
 * Shows a message to the user.
 *
 * @param text {string} the message to show.
 */
qx.Proto.showMessage = function(text) {
  ...
}

This comment describes the method showMessage. At the beginning there is a short text, describing the method itself. A @param attribute follows, describing the parameter text.

The docgenerator recognises the following structures:

/** Class definitions (resp. constructors). */
qx.OO.defineClass("mypackage.MyClass", blubb.MySuperClass,
function() {
  ...
});
 
/** Property definitions. */
qx.OO.addProperty({ name:"myProperty", type:qx.constant.Type.NUMBER });
 
/** Method definitions. */
qx.Proto.myMethod = function(bla, blubb) {
  ...
};
 
/** Static method definitions. */
qx.Class.myStaticMethod = function(bla, blubb) {
  ...
};
 
/** Constant definitions. */
qx.Class.MY_CONSTANT = 100;

The class description is taken as the first comment in the file which starts with /**. Therefore if you have a comment at the start of the file which has a first line of /**********, that will be taken as the class description, overriding any comment above the class itself. Therefore use /* ********* or /* ========== etc.

Within a doc comment the following attributes are supported:

Describes a parameter. After the @param comes the name of the parameter. Afterwards the type follows in curly brackets (Example: {Integer}), followed by the description text. Types are described more in detail in the next section.

When the parameter is optional, the curly brackets include the default value in addition to the type. The default value implies the value that has to be passed in, in order to get the same effect as when omitting the parameter. Example: {Boolean ? true}

You can also define multiple possible types. Example: {Boolean | Integer ? 0}

Describes the return value. After the @return comes the type in curly brackets followed by the description text.

Describes in which cases an exception is thrown.

Adds a cross reference to another structure (class, property, method or constant). The text is structured as follows: At first comes the full name of the class to link to. If you want to link to a property, method or constant, then a # comes, followed by the name of the property, method or constant.

If you refer to a structure within the same class, then the class name may be omitted. If you refer to a class in the same package, then the package name before the class may be omitted. In all other cases you have to specify the fully qualified class name (e.g. qx.ui.table.Table).

Some examples:

• qx.ui.form.Button refers to the class Button in the package qx.ui.form.
• qx.constant.Type#NUMBER links to the constant NUMBER of the class qx.constant.Type.
• qx.core.Init#defineMain refers to the method defineMain in the class qx.core.Init

After this target description an alternative text may follow. If missing the target description is shown.

The @link attribute is similar to the @see attribute, but it is used for linking to other structures within description texts. Unlike the other attributes, the @link attribute is not standalone, but in curly brackets and within the main description text or a description text of another attribute.

Example for a fully extended doc comment:

/**
* Handles a drop.
*
* @param dragSource {qx.bla.DragSource} the drag source that was dropped.
* @param targetElement {Element} the target element the drop aims to.
* @param dropType {Integer ? null} the drop type. This is the same type as used in
*        {@link qx.bla.DragEvent}.
* @return {Boolean} whether the event was handled.
* @throws if the targetElement is no child of this drop target.
*
* @see #getDragEvent(dragSource, elem, x, y)
* @see com.ptvag.webcomponent.ui.dnd.DragEvent
*/
qx.Proto.handleDrop = function(dragSource, targetElement, dropType) {?	
  ...
};

This comment is shown in the API viewer like this:?

Because JavaScript has no strong typing, the types of the parameters accepted by a method may not be read from the method’s definition. For showing the accepted types in the API documentation the data type may be specified in the doc attributes @param and @return.

The following types are accepted:

• Primitive: var, “void”, “undefined”
• Builtin classes: Object, Boolean, String, Number, Integer, Float, Double, Regexp, Function, Error, Map, Date and Element
• Other classes: Here the full qualified name is specified (e.g. qx.ui.core.Widget). If the referenced class is in the same package as the currently documented class, the plain class name is sufficient (e.g. Widget).

Arrays are specified by appending one or more [] to the type. E.g.: String[] or Integer[][].