Java and C# provide a uniform approach to documenting your code, but JavaScript is documented according to the developer’s preference (that is, if it’s documented at all). There is a movement within the Web community to develop a standard for documenting JavaScript code. One such proposed standard is ScriptDoc. (Note: ScriptDoc has no connection with the Microsoft tool for C# called AjaxDoc, which used to be named ScriptDoc.)

JavaScript comments

Before I discuss ScriptDoc in detail, it is worth mentioning the standard’s use of the inherent support for comments in JavaScript. Comments may be inserted anywhere within the code with double forward slashes (//) or use multi-line comments with the start comment (/*) and end comment (*/) combination. JavaScript comments are the groundwork for all JavaScript documentation standards currently being used or discussed.

ScriptDoc

The ScriptDoc approach will seem familiar to you if you know Java documentation techniques using the JavaDoc tool (C# also uses a similar approach). The crux of the design is the insertion of specially formatted or tagged comments within JavaScript files. These comments are extracted and placed within XML files, which other tools (or even human eyes) may consume.

ScriptDoc defines a number of tags that are used to document code. ScriptDoc’s online specification provides an overview of the currently available tags: here is a sampling of these tags:

  • @classDescription: Provides a description of a class.
  • @exception: Specifies the exception type that may be thrown by a function.
  • @param: Allows you to tag each parameter supported by a function.
  • @return: Specifies the data that may be returned by a function.

You can put ScriptDoc to use by following these basic instructions:

  • Each JavaScript function or class should include a documentation block before its declaration. The ScriptDoc parser automatically associates the block with the function or class immediately below it.
  • The JavaScript comment syntax is the basis for marking ScriptDoc documents; that is, each documentation block is enclosed within a slash-asterisk-asterisk (/**) and asterisk-slash (*/) markings. The ScriptDoc parser looks for these blocks.
  • The first line in the block should be a short description of the function or class. This applies to all documentation blocks except file descriptions.
  • After the first line provides a description, the previously described tags should be added to define features like parameters (@param) and return values (@return).

The following code sample displays the output of a function in a pop-up window:

/**

* Displays the greeting message


* @param {String} pName    A name to display with greeting.


* @return {String}   Returns a string value containing name and greeting


*/


<script type="text/javascript">


function getDisplayValue(pName) {


var sMsg = ', thanks for visiting.';


return(pName + sMsg);


}

</script>

It is a simple technique for providing coding details in your JavaScript code. If you don’t want to document your code inline within your JavaScript source, you may just insert @id tags in the function definition block and write most of your documentation in a separate file (using .sdoc file extension). The simple syntax in ScriptDoc is easy to use, but you may be wondering about support throughout the industry.

Industry acceptance

Web developers are fully aware of whether standards are accepted and embraced by the industry (the browser war provides plenty of examples). The process of assembling a JavaScript documentation standard and getting vendors to use it takes time, but ScriptDoc has one supporter with Aptana and its Aptana Studio IDE.

Aptana Studio uses ScriptDoc in its JavaScript files. The ScriptDoc comments are used by the code assist feature of the IDE, so you may get on-the-fly code assistance for your JavaScript, as well as what is included with Aptana Studio (jQuery included with the IDE is documented with ScriptDoc).

Another way to gather industry support is by getting JavaScript libraries to document themselves with ScriptDoc, as jQuery is with Aptana Studio. Another good example is the ff JavaScript library, which is fully documented using ScriptDoc.

Add meaning to your code

Web developers understand the importance of documenting their code. The problem with Web pages and applications is there is no accepted standard for documenting JavaScript. The ScriptDoc initiative aims to fill the void for JavaScript documentation code by building such a standard in a community-driven approach and slowly gaining industry acceptance. Take a look at ScriptDoc and see if you want to use this approach in your next project.

What are your thoughts about documenting your Web projects? Do you use ScriptDoc or another approach? Share your thoughts with the Web Developer community.

Tony Patton began his professional career as an application developer earning Java, VB, Lotus, and XML certifications to bolster his knowledge.

—————————————————————————————

Get weekly development tips in your inbox
Keep your developer skills sharp by signing up for TechRepublic’s free Web Developer newsletter, delivered each Tuesday. Automatically subscribe today!