Aptana Studio Help > Getting Started > Navigating Aptana Studio > Using Code Assist
Aptana Studio

ScriptDoc comprehensive tag reference

This page provides comprehensive documentation for using the ScriptDoc tags to document your code. If you just want to see a list of tags and short definitions, see the ScriptDoc tag quick reference.

Contents

Introduction

This reference page provides comprehensive documentation for all ScriptDoc tags, in alphabetical order.

Several tags have "synonyms" where you can use two differently named tags to document the same thing. You can use a synonym by using the exact same syntax as the original tag, but just substituting the tag name.

The section for each tag includes the following information:

* Example (Some tags have multiple examples)

Reference

The following tags are valid for code documentation:

@alias

ID for a class or function.

Applies to: Any

Syntax

@alias fooBar

Description

Use the @alias tag to ID a class or function if you have used a "shorthand" way to code the full name for that class or function.

Example

This example shows the @alias tag used to id a function called fooBar in the FOO.Lib namespace.

FOO.Lib.update(FOO.Lib) {
    
/**
 * Returns a function that will return a number one greater than the previous returned value, starting at n.
 * @alias fooBar
 * @alias FOO.Lib.fooBar
 * @param {Object} n    Number to start with. Default is 1.
 * @return {Function) Returns a function that will return a number one greater than the previous returned value.
 */
    fooBar: function (n/* = 1 */) {
        if (arguments.length === 0) {
            n = 1;
        }
        return function () {
            return n++;
        };
    },

@author

Author of a JavaScript file or function.

Applies to: Any

Syntax

@author Author-name [email]

Description

Use @author to credit the author of a JavaScript file or function.

Example

This example shows the @author tag used with the @fileoverview and @version tags to provide header information for a JavaScript file.

/** 
* @projectDescription   Joe Smith's wonderful JavaScript library.
*
* @author       Joe Smith jsmith@company.com
* @version      0.1 
*/

@classDescription

Description of the class.

Applies to: Function

Syntax

@classDescription Description

Description

Use the @classDescription tag to give a short description of the class (if applicable).

Example

This example shows a sample documentation block for a basic Shape class.

/**
* Create a new instance of Shape.
*
* @classDescription     This class creates a new Shape.
* @return {Shape}       Returns a new Shape.
* @type {Object}
* @constructor  
*/
function Shape() {
}

@constructor

Shows that a function is a constructor for a class.

Applies to: Function

Syntax

@constructor

Description

Use the @constructor tag to signify that a function is a constructor if you are coding in an object-oriented programming style.

Example

This example shows a sample documentation block for a basic Shape class.

/**
* Create a new instance of Shape.
*
* @classDescription     This class creates a new Shape.
* @return {Object}      Returns a new Shape object.
* @constructor  
*/
function Shape() {
}

@deprecated

Signifies that a function or a property has been deprecated.

Applies to: Function or property.

Syntax

@deprecated

Description

Use the @deprecated tag to show that a function or a property has been deprecated and should not be used.

Example

This example shows a @deprecated tag added to a documentation block for a function.

/**
* This function gets a foo by name.
* @param {Object}       fooName Name of the foo to retrieve.
* @return {Object}      Returns a new foo.
* @deprecated
*/

@exception

Specifies the type of exception thrown by a function.

Applies to: Function

Syntax

@exception {Exception} Exception-description

Description

Use the @exception tag to specify any exceptions thrown by a function. You can specify multiple exceptions in a documentation block.

Example

This example shows a function that throws two exceptions--a "MemoryException" and a "GeneralShapeException".

/**
* This function creates a new Shape object. 
*
* @exception    {MemoryException}       Throws a memory exception if out of memory. 
* @exception    {GeneralShapeException} Throws a general shape exception if the object is not a shape.
* @return       {Object}        Returns a new shape object.
*/

@id

Unique identifier for a function or property.

Applies to: All

Syntax

@id identifierName

Description

Use @id to link a function or property to its documentation in an external @sdoc file. Add the @id tag both inline right above a function and to the documentation block in the .sdoc file to create the link.

Example

This example shows an inline @id tag for the function foo.

/** @id */
function foo() {
   alert("Foo!");
}

@inherits

Indicates that one item "inherits" from another

Applies to: Function

Syntax

@inherits functionNameA
@inherits functionNameB

or

@inherits functionNameA, functionNameB

Description

Use @inherits to indicate that one "class" subclasses another in object-oriented JavaScript.

Example

This example shows that bar inherits from foo.

function foo() {
}

/** @inherits foo */
function bar() {
}


@memberOf

Signifies that a function is a member of the specified class.

Applies to: Function, Property.

Syntax

@memberOf Class

Description

Use the @memberOf tag to signify that a function is a member of the specified class.

Example

This example shows that the getFoo function is a member of the fooBar class.

/**
* @memberOf fooBar
*/
function getFoo(){
}

@method

Signifies that a function is a method of a class, if applicable.

Applies to: Function

Syntax

@method

Description

Use the @method tag to signify a method of a class if you are coding in an object-oriented programming style.

Example

This example shows a @method tag.

/**
* @method
*/

@namespace

Creates the namespace prefix for a library file.

Applies to: File

Syntax

@namespace namespaceName

Description

Creates the link between the namespace of a library file and an external .sdoc file.

Example

This example shows how to use the @namespace tag to link the namespace of a library to an .sdoc file.

The excerpt below would go at both the top of the library file that contains the "ajax" namespace for the "snazzyLib" library and the corresponding "ajax.sdoc" file that contains the documentation for the "ajax" namespace in snazzyLib:

/**
 * @namespace snazzyLib.ajax
 */

@param

Use @param to tag each parameter for a function.

Applies to: Function

Syntax

@param {Type[, Type, ... ]} [Parameter |...] Parameter-Description

Description

Gives information about a parameter for a function. Specify the data type between the curly braces. If the parameter is optional, add '[]' around the parameter name.

Examples

Standard example

The following example shows a parameter for a function that takes a String named myDog.

/**
 * @param {String} myDog The name of the dog. 
 */

Optional parameter example

The following example shows an optional parameter that can be either a String or a Date.

/**
 * @param {String, Date} [myDate] Specifies the date, if applicable.
 */

Multiple objects example

The following example shows a parameter that can be one or more Strings.

/**
 * @param {String} ... Takes one or more dog parameters.
 */


@projectDescription

Gives a description of a JavaScript file.

Applies to: File.

Syntax

@projectDescription Description

Description

Use the @projectDescription tag as the first tag in the first documentation block for a JavaScript file. The @projectDescription tag signifies that the entire documentation block is part of a project description.

Example

This example shows the @projectDescription tag used with the @author and @version tags to provide header information for a JavaScript file.

/** 
 * @projectDescription  This library contains a lot of classes and functions.
 *
 * @author      Joe Smith jsmith@company.com
 * @version     0.1 
 */

@property

Indicates that a member is a property of a class instance

Applies to: File.

Syntax

@property {Type [, Type, ...]}

Description

Use the @property tag to indicate that the following member is a property (as opposed to a method) of a class instance.

Example

This example shows the @property tag being used to define a "myProperty" property on the MyClass class. The property contains a description and will be treated as a String.

/** 
 * This is a property of class MyClass
 *
 * @alias MyClass.myProperty
 * @property {String}
 */


@return

Specifies information about the return value(s) of a function.

Applies to: Function

Syntax

@return {Type [, Type, ...]} Returns-Description

Description

@return gives a description for the return value of a function.

Example

This example shows a return value for a function that returns a new foo object.

/** 
 * @return {Object} Returns a new foo object.   
 */

@sdoc

Defines the path to an external .sdoc file for a library file.

Applies to: File

Syntax

@sdoc filePath

Description

Associates an external @sdoc file with a JavaScript file. Use either a relative or absolute path.

Example

This example shows a documentation block that associates an "ajax.sdoc" file in the "scripts/snazzyLib" directory with the current JavaScript file:

/**
 * @sdoc scripts/snazzyLib/ajax.sdoc
 */

@see

Links to another related class or function.

Applies to: Any

Syntax

@see Class | #Function | Class#Function

Description

Use the @see tag to add a link to another class, a function within the current class, or a function in another class.

Examples

Function example

This example shows a link to a function named "foo" in the same class as the one being documented.

/**
 * @see #foo
 */

Class example

This example shows a link to a class named "fooBar".

/**
 * @see fooBar
 */

Function in another class example

This example shows a link to a function named "foo" in another class named "fooBar".

/**
 * @see fooBar#foo
 */

@since

Specifies since which version the library, function, or property became valid.

Applies to: File, Function, Property

Syntax

@since Version-number

Description

Specifies since which version the library, function, or property became valid.

Example

This example shows a @since tag, used in conjunction with @projectDescription, @author, and @version tags. A documentation block like this would go at the top of a JavaScript file.

/** 
 * @projectDescription  This library contains a lot of classes and functions.
 *
 * @author      Joe Smith jsmith@company.com
 * @version     1.1 
 * @since       1.0
 */

@type

Specifies what data type a property is.

Applies to Property

Syntax

@type {Type}

Description

Specifies what data type a property is.

Example

This example uses the @return tag with the @type tag to show the return type for a function that creates a new foo.

/**
 * This property describes what type of shape an object is.
 * @type {Object} This property describes what type of shape an object is.
 */

@version

Specifies the version number of the JavaScript file or class.

Applies to: Any

Syntax

@version Version-Number

Description

Specifies the version number of the JavaScript file or class.

Example

This example shows the @version tag used with the @projectDescription and @author tags to provide header information for a JavaScript file.

/** 
 * @projectDescription A description of the file ahead
 *
 * @author      Joe Smith jsmith@company.com
 * @version     0.1 
 */

Related Topics