JS: Should describe 3 types of comment delimiters, not 2.

[Krxtopher]

I think we should call out 3 types of comments:

• doc comments - Comments placed immediately before function and class declarations that are meant to be parsed by a doc generation tool
• multi-line comments - Meant to be read inline in the code only, not output via auto doc generation
• single-line comments

This is consistent with how many editors and IDEs classify comments and more closely matches how developers should think about comments (IMHO).

Doc comment example:

/**
 * Calculates an estimated shipping cost for a set of products. If the value
 * of "products" is null or an empty array, -1 is returned.
 *
 * @param products
 *        An array of ProductInfo objects.
 * @return
 *        A number expressed in US dollars
 */
function estimateShipping(products) {
    …
}

Multi-line comment example:

/* 
This is a multi-line comment and is being used
because we're describing something a bit complex.
*/

Single-line comment example:

// Single-line comment for short notes.

[nicetransition]

There's a 4th type too /*! for licensing of libraries

[lukeaskew]

Should we also add a standard that developers should use Java Doc syntax for commenting?

[nicetransition]

I like that suggestion. You could just link to their how-to page

[lukeaskew]

I am not extremely familiar with the differences in autodoc syntax.

For JavaScript, what should we recommend? Javadoc, JSdoc, YUIdoc?

[Krxtopher]

Unless we're ready to standardize on an auto doc tool I don't think that we have to endorse a specific syntax in this general standards document. Regardless of which doc comment syntax is used on a project, they almost all use the double star convention to denote a doc comment.

[lukeaskew]

Should we wait to include the doc comment example until the syntax is standardized?

[nicetransition]

Yes, let's hold on that and revisit at a later time