Documenting your code in an .sdoc file

This page describes how to document your JavaScript code using an external .sdoc file instead of inline comments.

Introduction

Documenting your JavaScript code with Aptana's ScriptDoc system allows you to instantly access your documented functions through Code Assist. You can add ScriptDoc documentation blocks either inline (see Documenting your code using ScriptDoc) or in an external file so that your comments are not in the .js file that contains your code. This Help topic describes how to set up a .sdoc file so that you can document your functions externally and still take advantage of Code Assist.

Instructions

To set up an .sdoc file for documenting your code externally:

In the same directory as the JavaScript (.js) file that you want to document, create an empty text file with the same name as the .js file.
Change the file extension from ".txt" to ".sdoc". The .sdoc file extension is recognized by Aptana as part of ScriptDoc.
At the top of both the .js and .sdoc file, add @namespace tags (shown below) to link the two files. You can use the same comment block at the top of both files:
```
/**
 * @namespace myLibrary.myNamespace
 */
```
If the .sdoc file will reside somewhere other than the same directory as the .js file, in the comment block for the .js file, also add an @sdoc tag with the path to the place where the .sdoc file will be.
In your JavaScript file, add @id tags above each function, class, and object that you want available to Code Assist. The example below shows an @id tag for a simple function called "foo".
```
/** @id foo */
function foo() {
    alert("Foo!");
}
```
In the corresponding .sdoc file, add the documentation blocks that will correspond to the @id tags in the .js file. Include the matching @id tags (these will link the documentation blocks back to the appropriate id's in the .js file) and @alias tags, which is how the function will appear in Code Assist.
Once the files are linked, any Code Assist Profile that you create for the .js files will automatically pull in the corresponding .sdoc files if you have linked them using the @namespace tags.

For an example of .js files that were documented with .sdoc files, see the documented version of MochiKit. Work through the Getting started with Aptana and MochiKit walkthrough to see how all of the files work together.

Documenting your code in an .sdoc file

Introduction

Instructions

Related Topics