Question

我总是以下列格式看到JSDoc（以及之前的JavaDoc）：

 /**
  * This is some JSDoc ...
  * ... and some more
  */
 function foo() {

然而，我的同事宁愿不要使用最初的星号，即：

 /**
    This is some JSDoc ...
    ... and some more
  */
 function foo() {

当我在Eclipse中尝试这个时，它仍然将代码识别为JSDoc（它的颜色与非JSDoc注释不同）。但是，当我查看JSDoc网站时，所有示例都包含星号......但是再一次，我找不到任何说它们都需要的东西（说实话，JSDoc网站看起来很糟糕）。 / p>

所以，鉴于我甚至找不到JSDoc是什么/不是什么的正确规范，我想我会问Stack Overflow。这里的任何人都可以指出：

A）某种规范参考（例如来自JSDoc网站的东西）说初始星号是不需要的

B）没有初始星号的例子会有问题（例如“你不能使用酷的JSDoc库X，除非你有初始的星号”）

的的 *编辑*

为了澄清，我们目前不使用JSDoc文档生成器。这个问题更多地来自于希望以行业标准的方式格式化我们的评论，并希望（将来的某一天）能够使用依赖于JSDoc标准的工具（例如JSDOc documentaiton生成器）。 p>

基本上我并不关心我的同事如何格式化他的JSDoc，我只是不希望非标准的做法在将来导致问题（如果我们将来有这样的问题，我我希望能够向他解释，而不只是说“我不喜欢你格式化JSDoc的方式”。）

Answer 1

没有“行业标准”的jsdoc格式。 jsdoc 3以某种方式运作，jsdoc 2以类似但不同的方式运作。有一个jsdoc 1，但我不知道仍然在生产中使用它的任何情况。然后有一些工具尝试使用jsdoc的标记，或多或少成功。

行开头的星号是可选的通常是正确的但并非在所有情况下都是如此。例如，如果将jsdoc 3与Markdown plugin一起使用，那么：

另外，请务必在文档注释中使用前导星号！如果省略前导星号，JSDoc的代码解析器可能会删除用于Markdown格式的其他星号。

因此jsdoc的各种版本都没有要求领先的星号，但是有一些用例场景，其中绝对需要主要的星号。（我没有在jsdoc 3的文档中找到一个位置，直接说明星号是可选的。但是，上面的引用暗示它们是。）

但有一件事，在这里提出的问题中，两个代码段都以/*开头。 jsdoc的所有版本，从jsdoc 1到jsdoc 3，需要将注释作为jsdoc注释处理，并在开头标记为with two or more asterisks，如/**。

Answer 2

我从mozilla找到了这个旧的link about jsdoc compiler，其中包含以下行：

// Strip leading whitespace and "*".
comment += s.replace(/^\s*\*/, "");
s = f.readLine();

所以看起来每行的星号都不是强制性的，而是@Dr。 McKay说只适用于布局（如果它仍然在使用或者是当前jsdoc的基础）。