This documentation relates to previous versions of Titanium Studio.

To see the latest documentation, visit docs.appcelerator.com.

Skip to end of metadata
Go to start of metadata

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:

  • Short description of the tag
  • Syntax
  • What the tag applies to
  • Longer explanation of the tag
  • 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.

@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.

@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.

@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.

@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.

@example

Gives an example for the function being documented.

Applies to: Any (except @projectDescription)

Syntax

@example Example-code

Description

Use the @example tag when you want to show an example of how to use the code that you are documenting. Any whitespace you add will be included when the tag is parsed. You can also include basic HTML to make your example more readable.

Example

This example shows a documentation block for a "move" function that takes the arguments "layerID" and "direction" and includes an @example tag with code example. Use HTML tags to format your descriptions. Use the

{code}{code}

tag set to format the example as code. (This example uses the @remarks tag to give more information about the function.)

@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".

@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.

@inherits

Indicates that one item "inherits" from another

Applies to: Function

Syntax

or

Description

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

Example

This example shows that bar inherits from foo.

@internal

Specifies that a function or property should not be made visible by Content Assist.

Applies to: Function, Property

Syntax

@internal

Description

Specifies that a function or property should not be made visible by Content Assist.

Example

This example shows an @internal tag.

@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.

@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.

@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:

@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.

Optional parameter example

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

Multiple objects example

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

@private

Signifies that a class or a function is private.

Applies to: Function, Property

Syntax

@private

Description

Use the @private tag to signify that a class or function is private. The ScriptDoc output will not include private classes or functions unless you run ScriptDoc with the --private commmand line argument.

Example

This example shows a private function that returns a foo.

@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.

@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.

@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.

@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.

Class example

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

Function in another class example

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

@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.

@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.

@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.

Labels
  • None