Using Aptana's ScriptDoc system to document your code enables Code Assist to work for your own code in addition to built-in support the core JavaScript language and many popular Ajax JavaScript libraries. This page gives some of the guidelines to think about when adding ScriptDoc blocks to your code.
Peter Geil has posted a nice one page cheat sheet for ScriptDoc on Scribd.
Contents |
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 look up a tag once you are familiar with the syntax for each tag.
- As an alternative to inline comments in your JavaScript file, you may insert @id tags above your JavaScript functions and store the documentation in a separate .sdoc file.
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