How to Write JavaScript API Documentation Comments in IDEs

When writing code in IDEs (Visual Studio, Eclipse, Netbeans, Aptana, etc.), developers need to find useful APIs and relevant documentations quickly. The assist function (e.g. IntelliSense) is usually triggered by the shortcut keys Ctrl + space. See the screenshots of Microsoft Visual Studio and Netbeans.

vs_content_assistnetbeans_content_assist

All smart IDEs could automatically identify the defined methods in JS files, though, with the well-defined documentation comments, all methods could be more readable and understandable. To facilitate developers, Dynamsoft used two kinds of JavaScript documentation comment style in Dynamic Web TWAIN HTML5 SDK. One, which starts with **///**', is used for Microsoft Visual Studio IntelliSense. The other, which starts with /’ and ends with `*/**’, is used for Netbeans, Eclipse, and other mainstream IDEs.

Comparison of JavaScript Documentation Comment Style

Microsoft Visual Studio IntelliSense supports both styles. To make IntelliSense work in JS file, we need to include the directive `/// ’ at the first line. For example:

/// <reference path="dynamsoft.webtwain.vs.js"/>
var DWObject = Dynamsoft.WebTwainEnv.GetWebTwain();

Try to define and use the method Crop:

  • Starting with `///’

      Dynamsoft.WebTwain.prototype.Crop = function(sImageIndex, left, top, right, bottom) {
      /// <summary>
      /// Crops the image of a specified index in buffer.
      /// </summary>
      /// <param name="sImageIndex" type="short">specifies the index of image in buffer. The index is 0-based.</param>
      /// <param name="left" type="int">specifies the x-coordinate of the upper-left corner of the rectangle.</param>
      /// <param name="top" type="int">specifies the y-coordinate of the upper-left corner of the rectangle.</param>
      /// <param name="right" type="int">specifies the x-coordinate of the lower-right corner of the rectangle.</param>
      /// <param name="bottom" type="int">specifies the y-coordinate of the lower-right corner of the rectangle.</param>
      /// <returns type="bool"></returns>
  };

    vs_jsdoc_vs

  • Starting with `/**’

      /**
   * Crops the image of a specified index in buffer.
   * @method Dynamsoft.WebTwain#Crop 
   * @param {short} sImageIndex specifies the index of image in buffer. The index is 0-based.
   * @param {int} left specifies the x-coordinate of the upper-left corner of the rectangle.
   * @param {int} top specifies the y-coordinate of the upper-left corner of the rectangle.
   * @param {int} right specifies the x-coordinate of the lower-right corner of the rectangle.
   * @param {int} bottom specifies the y-coordinate of the lower-right corner of the rectangle.
   * @returns {bool}
   */
  Dynamsoft.WebTwain.prototype.Crop = function(sImageIndex, left, top, right, bottom) {
  };

    vs_jsdoc

Which one do you prefer? The **///**' seems more user-friendly than /**’, because it’s uniquely used for IntelliSense. We can try the different comment styles in another IDE Netbeans:

netbeans_jsdoc

There are two methods called AcquireImage() in the figure. The undefined one contains the comment which starts with **///**'. Apparently, the ///’ style is not compatible with other IDEs besides Microsoft Visual Studio.

If you want to wrap your JavaScript methods for other developers, don’t forget to add detailed documentation comments, as well as choose the right comment style for the target IDEs.

Source Code

https://github.com/DynamsoftRD/Web-TWAIN-JavaScript-Comments

References