What is the preferred method of commenting JavaScript objects and methods?
JavascriptCommentsJavascript Problem Overview
I'm used to Atlas where the preferred (from what I know) method is to use XML comments such as:
/// <summary>
/// Method to calculate distance between two points
/// </summary>
///
/// <param name="pointA">First point</param>
/// <param name="pointB">Second point</param>
///
function calculatePointDistance(pointA, pointB) { ... }
Recently I've been looking into other third-party JavaScript libraries and I see syntax like:
/*
* some comment here
* another comment here
* ...
*/
function blahblah() { ... }
As a bonus, are there API generators for JavaScript that could read the 'preferred' commenting style?
Javascript Solutions
Solution 1 - Javascript
There's JSDoc
/**
* Shape is an abstract base class. It is defined simply
* to have something to inherit from for geometric
* subclasses
* @constructor
*/
function Shape(color){
this.color = color;
}
Solution 2 - Javascript
The simpler the better, comments are good, use them :)
var something = 10; // My comment
/*
Lorem ipsum dolor sit amet, consectetur adipisicing elit,
sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco
nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
in reprehenderit in voluptate velit esse cillum dolore eu
fugiat nulla pariatur.
*/
function bigThing() {
// ...
}
But for autogenerated doc...
/**
* Adds two numbers.
* @param {number} num1 The first number to add.
* @param {number} num2 The second number to add.
* @return {number} The result of adding num1 and num2.
*/
function bigThing() {
// ...
}
Solution 3 - Javascript
Yahoo offers YUIDoc.
It's well documented, supported by Yahoo, and is a Node.js app.
It also uses a lot of the same syntax, so not many changes would have to be made to go from one to the other.
Solution 4 - Javascript
The use of the triple comment in the first example is actually used for external XML documentation tools and (in Visual Studio) intellisense support. Its still a valid comment, but its special :) The actuall comment 'operator' is // The only limitation there is that its for a single line.
The second example uses C style block commenting which allows for commenting across multiple lines or in the middle of a line.
Solution 5 - Javascript
Try pasting the following into a javascript file in Visual Studio 08 and play around with it:
var Namespace = {};
Namespace.AnotherNamespace = {};
Namespace.AnotherNamespace.annoyingAlert = function(_message)
{
/// <param name="_message">The message you want alerted two times</param>
/// <summary>This is really annoying!!</summary>
alert(_message);
alert(_message);
};
Intellisense galore!
More info about this (including how to reference external javascript-files, for use in large libraries) can be found on http://weblogs.asp.net/scottgu/archive/2007/06/21/vs-2008-javascript-intellisense.aspx">Scott Gu's blog.