Using Studio's ScriptDoc system to document your code enables Content Assist to work for your code in addition to built-in support the core JavaScript language. This page gives some of the guidelines to think about when adding ScriptDoc blocks to your code.
A nice one-page cheat sheet for ScriptDoc on Scribd is posted.
Basic Instructions
- Add a documentation block immediately before each function or class. The ScriptDoc parser automatically associates the documentation block with the function or class following it.
-
Enclose each documentation block within a slash-asterisk-asterisk
(/**)
and asterisk-slash
(*/)
comment set.
- The first line in the block, except for file overviews, should be a short description of the function or class.
- After the description, add tags that explain the function, including a description, what parameters it takes, and its return type. You can also use the ScriptDoc tag quick reference to quickly lookup a tag once you are familiar with the syntax for each tag.
Example: A basic documentation block for a getFoo() function
/** * Gets the current foo * @param {String} fooId The unique identifier for the
foo.* @return {Object} Returns
the current foo.*/function getFoo(fooID){} |
Ordering your tags
Add your tags in the following order, as appropriate:
- @classDescription (constructors only)
- @param (classes, interfaces, functions, and constructors only)
- @return (functions only)
- @type (functions only)
- @author (classes and interfaces only, required)
- @version (classes and interfaces only, required)
- @see
- @since
- @deprecated
Guidelines for ordering multiple versions of the same tag
- @author - List @author tags chronologically, starting with the author who created the file or function.
- @param - List @param tags in argument declaration order.
- @see - List @see tags from nearest to furthest access, shown below:
@see #Constructor(Type, Type...)@see #Constructor(Type id, Type id...)@see #method(Type, Type,...)@see #method(Type id, Type, id...)@see Class@see Class#field@see Class#Constructor(Type, Type...)@see Class#Constructor(Type id, Type id)@see Class#method(Type, Type,...)@see Class#method(Type id, Type id,...)@see package.Class@see package.Class#field@see package.Class#Constructor(Type, Type...)@see package.Class#Constructor(Type id, Type id)@see package.Class#method(Type, Type,...)@see package.Class#method(Type id, Type, id)@see package |