Ajax Basics Tutorial (5)-5.1 document using JSDoc to build JavaScript code

As an experienced Web application developer, you may be able to skillfully apply some server-side technology (or a variety of server-side technologies) to build Web applications. We have seen that over the past few years, server-side technology has developed significantly, server-side software development is becoming more and more easy, and more robust, in contrast, the client technology is basically left aside. This situation has been improved by the advent of Ajax technology, as developers now have a richer client toolbox with a large number of tools to use. You may not be used to using a lot of HTML, JavaScript, and CSS, but you have to do this if you want to implement AJAX technology. The tools and techniques described in this chapter make it easier to develop AJAX applications. This chapter is not an in-depth, comprehensive tutorial, but a quick primer for these useful tools and technologies.

5.1 Document using JSDoc to build JavaScript code

Like many other programming languages, JavaScript has a fundamental flaw in the general software developers ' view: writing (or rewriting) a feature is usually relatively easy, but it's not easy to read existing code and make it clear how it works. Annotations can be added appropriately when writing code, so that when other developers understand how the code works, especially to modify the functionality of the code, they can reduce their burden and save their time and effort.

The Java language introduces a tool called Javadoc. This tool generates API documentation in HTML format based on documentation comments in the source code. The generated HTML document can be read on any Web browser, and because it is generated in HTML format, it can be published online so that developers can easily access the documents. Provide API documentation in a format that can be easily browsed, which allows developers to understand how a class or method behaves and how to use it without having to look at the source code carefully.

JSDoc is a similar tool for JavaScript (jsdoc.sourceforge.net). JSDoc is an open source tool that is published using the GPL (GNU public License) protocol. JSDoc is written in Perl, which means that Windows users must have a Perl run-time environment installed. (and for most Linux and Unix operating systems, Perl is one of the standard parts).

5.1.1 Installation

To use Jsdoc,windows users must install a Perl environment, such as ActivePerl (Www.activeperl. COM). You must also install a nonstandard Perl module named Html::template (www.cpan.org). The JSDoc Project Web page provides instructions and can be consulted if you need help.

JSDoc is released as a compressed tarball. To install JSDoc, you simply download tarball from the JSDoc Project Web page, untie it to the specified directory, enter the JSDoc directory, and enter the following command to test JSDoc:

Perl jsdoc.pl Test.js

JSDoc saves the resulting HTML file to a directory named Js_docs_out. Open the Index.html file in this folder to browse the documents generated from the Test.js file.

5.1.2 Usage

Now that you know something about JSDoc, you might be wondering how to use jsdoc to generate documentation for your JavaScript code. Table 5-1 lists some of the special jsdoc tags that can be used to create HTML documents. These tags are not unfamiliar to people who have written Javadoc annotations in Java code. Each comment block that is included in the build document must start with/** and end with the/*.

Table 5-1 jsdoc Command Properties

Command name	Description
@param @argument	Specify parameter names and descriptions to describe a function argument
@return @returns	Describes the return value of a function
@author	Indicates the author of the Code
@deprecated	Indicates that a function has been deprecated and will be completely deleted in future versions of the code. To avoid using this piece of code
@see	Creates an HTML link that points to the description of the specified class
@version	Specify a release version
@requires	Creates an HTML link that points to the specified class required by this class
@throws @exception	Describes the types of exceptions that a function might throw
{@link}	Creates an HTML link that points to the specified class. This is similar to @see, but {@link} can be embedded in the comment text
@fileoverview	This is a special marker. If you use this tag in the first document block of a file, specify that the remainder of the document block will be used to provide an overview of the file
@class	Provides information about the class, used in the document of the constructor
@constructor	Make it clear that a function is a constructor of a class
@type	Specify the return type of the function
@extends	Indicates that a class derives another class. JSDoc usually detects this information by itself, but in some cases you must use this tag