Documenting your code using ScriptDoc

From Aptana

This page gives some of the guidelines to think about when documenting your code using the Aptana ScriptDoc system.

Contents

Introduction

By using Aptana's ScriptDoc system to document your code, you enable Code Assist to work for your own code and not just the core JavaScript language and HTML DOM.

Instructions

Document your code by using documentation blocks. Follow the guidelines below to write your documentation blocks.

Basic Instructions

To document your code:

  • Add a documentation block directly above each function or class in your code. The ScriptDoc parser will automatically associate the documentation block with the function or class immediately below it.
  • Enclose each documentation block within a slash-asterisk-asterisk (/**) and asterisk-slash (*/) comment set.
  • For all documentation blocks (except a file overview), the first line in the block should be a short description of the function or class.
  • After the first sentence, add the tags that give information about the function, such as what parameters it takes and its return type. See the ScriptDoc comprehensive tag reference to learn about the different tags. (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.)
  • If you do not want to document your code inline as part of your JavaScript file, you can just insert @id tags above your JavaScript functions and write most of your documentation in a separate .sdoc file. See Documenting your code in an .sdoc file for information about documenting your code in an external file.

This example shows 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

Ordering multiple versions of the same tag

If you have multiple versions of the same tag (e.g. a function that takes multiple parameters), use the guidelines below to help you order them

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

Related Topics