jQuery: JSDoc and plugin development

There's a widespread trend in jQuery's coding that gets developers accustomed to the bad practice of not following a common comment standard while developing plugins. A well-commented plugin is more useful than a plugin where comments are simply put in the code without any discernible order or meaning. That's where JSDoc comes into play.

JSDoc overview

In Java there is a tool called javadoc. This tool creates the API's documentation in HTML format by using comments inserted in the source code. JSDoc is a similar tool for JavaScript. The following table shows the special tags used for creating the HTML documentation. Each comments block must start with /** and end with */.

JSDoc tags

Tag	Description
@param @argument	A parameter of a function, with its name and description.
@return @returns	The returned value of the function.
@author	The author of the code.
@deprecated	The function is not approved and can be removed.
@see	Creates a HTML link with a description of the specified class.
@version	Specifies the released version.
@requires	Creates a HTML link with the specified class required by that class.
@throws @exception	Describes the type of exception generated by a function.
@link	Creates a HTML link with the specified class. Similar to @see, but embedded in the comment's text.
@fileoverview	Special tag. When used in the first documentation's block, specifies that this block should be used for providing an introduction to the file itself.
@class	Provides information about the class and it's used in the constructor's documentation.
@constructor	Specifies a function as a class constructor.
@type	Specifies the type returned by a function.
@extends	Specifies that a class works as a sub-class of another one.
@private	Specifies that a class or function is private.
@final	Specifies that a value is a constant type.
@ignore	JSDoc ignores the functions marked with this tag.
@member	Shows that a function is a member of a given class.
@base	Forces JSDoc to view the current class constructor as a subclass of the class given as the value to this tag.
@addon	Marks a function as being an addon to a core JavaScript function that isn't defined within your own sources.
@exec	Forces JSDoc to "execute" this method as part of its preprocessing step, in the same way that class contructors are executed. This can allow attributes to be added to a class from within a function.

Using JSDoc in plugins

You can use JSDoc in several ways while writing your plugin code. For example, at the beginning of the file:

/** @fileoverview jTweet - A jQuery plugin for Twitter
 *  @author  Gabriele Romanato
 *  @version 1.0
 *  @requires jQuery
 */

Or in a plugin function:

/** Turns a textual URL into an HTML link
 *  @private
 *  @param String url The textual URL
 *  @returns String link The HTML link
 */
 
function formatTwitterURLs(url) {

  // ...
  
  return link;

}

JSDoc is really useful, especially when you're dealing with object-oriented plugins or jQuery UI-like widgets.