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.

This entry was posted in by Gabriele Romanato. Bookmark the permalink.

One thought on “jQuery: JSDoc and plugin development”

  1. I cannot get this working widget methods. Is there any more complete examples how to document a Query UI widget with jsdoc?

Leave a Reply

Note: Only a member of this blog may post a comment.