Web Development

Write JavaScript documentation with the ScriptDoc standard

ScriptDoc is a tool that extracts documentation from JavaScript files and packages it into XML files that can be consumed by documentation building tools. This approach is beginning to gain traction within the Web development community.
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!

About

Tony Patton has worn many hats over his 15+ years in the IT industry while witnessing many technologies come and go. He currently focuses on .NET and Web Development while trying to grasp the many facets of supporting such technologies in a productio...

10 comments
fedm235
fedm235

"comments with...double backslashes (//)" really, these are forward slashes.

Hendry_Betts
Hendry_Betts

Ok, so let's say I subscribe to this documentation standard. I even get buy-in from the rest of my development team! Great!!! But what good does it do? There is only one vendor that supports it (to date), it does not produce human readable documentation like JavaDoc does. There is no tool that will take the XML and create human readable documentation. So I have invested untold hours to get my team to "do the right thing" -- and don't get me wrong, I think this is the right thing -- with no ROI. My Junior developers are still standing around staring at the well documented code and not understanding it.

Ascalonian
Ascalonian

The issue with JSDocs and ScriptDoc is that you are limited to only the tags they provide you. What if you want to show more, for example pre-req , post-req, initialized value and notes? You cannot with a finite set of tags. However, with Natural Docs [http://www.naturaldocs.org/], you are not limited. You can make any header or tag you want, provide hover-over to see code snippets, and customizable interface. I do not like being told or limited on what I can use. This allows freedom for all scripting

aspatton
aspatton

Thanks for the correction, I appreciate it.

Justin James
Justin James

I've let the right folks know so that we can get that corrected, thanks! J.Ja

rdakin
rdakin

that caught my eye too.

SnoopDougEDoug
SnoopDougEDoug

"There is no tool that will take the XML and create human readable documentation." Yes there is. It's called XSLT. doug

aspatton
aspatton

It seems like limitations are necessary within a standard. If it allows everybody to create their own tags and such, then what good is the standard for enforcing consistency?

adfunches
adfunches

This exasperating "800 Pd Gorilla" is driving me NUTS! Where can I find the download for this XSLT that will be compatible with a MAC 10.3.9 running MS Office Suite? PLEASE HELP! I am NOT an IT Tech, just a Rube attempting to cope ... Cheers, Tony Funches

Editor's Picks