JavaScript中代码注释的正确方法是什么？

Question

Javascript中代码注释的正确方法是什么 - 与Java中的语法相同？哪些工具实际上会利用这些评论：

  /*
  * Add an element to the group
  * @param {Object}  overlayElement
  * @param {Object} [element2] optional element
  */ 

我发现新的Resharper 6（我在VisualStudio 2010中编写JS）提供与C＃中相同的注释，但仅在函数体内，类似于/// <param name="overlayElement"></param> 。 ReSharper没有突出显示JS代码注释。

什么是最好的方式...？

Answer 1

使用//比/* */更好，因为那时你可以使用后者来取出包含其他注释的整个块。但是，如果要使用自动文档生成工具，则必须使用类似于javaDoc样式的注释。

这是一个适用于YUI DOC（最好的一个）https://yui.github.io/yuidoc/的例子

/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} some string
* @param {Object} some object
* @return {bool} some bool
*/

Answer 2

好的做法是使用//而不是/* */

原因是因为如果你在评论的任何部分都有*/（假设你还没有打算结束），它将结束评论。即使*/在一个字符串中，也会发生这种情况。即"*/"

注意//在换行符结束，所以你需要//的每一行评论。

Answer 3

一个很好的例子是基于Java的评论，它也与JSDoc一起使用。你可以在这里找到例子：http://code.google.com/p/jsdoc-toolkit/wiki/FAQ

要将简单的在线人员添加为评论，//仍然是评论代码的好方法。但是为了生成文档，我会使用JSDoc语法。我过去曾经使用它，效果很好。