星号对“有效”JSDoc是否必要？

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网站似乎有点糟糕)。

因此，考虑到我甚至无法找到关于JSDoc是什么/不是什么的适当规范，我想我会问Stack溢出。这里有人能指给我看吗

( A)某种标准引用(例如。(来自JSDoc站点的东西)说最初的星号是/不需要的

没有初始星号的例子将是有问题的(例如。“除非你有初始星号，否则你不能使用酷的JSDoc库X”)

*编辑*

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

基本上，我并不关心我的同事如何格式化他的JSDoc，我只是不想让一个非标准的实践在将来造成问题(如果我们未来有这样的问题，我想向他解释，而不仅仅是说“我不喜欢你格式化JSDoc的方式”)。

Answer 1

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

行开头的星号通常是可选的，但并非所有情况都是可选的。例如，如果在标价插件中使用jsdoc 3，那么：

另外，一定要在文档注释中使用前导星号！如果省略了前面的星号，JSDoc的代码解析器可能会删除用于标记格式的其他星号。

因此，各种版本的jsdoc并不需要领先的星号，但是有一些用例场景，其中绝对需要领先星号。(我还没有在jsdoc 3的文档中找到一个直接声明星号是可选的位置。然而，上面的引文意味着它们确实是。

但有一点是，在这里提出的问题中，两个代码片段都以/*开头。jsdoc的所有版本(从jsdoc 1到jsdoc 3)都需要将作为jsdoc注释处理的注释在开始时标记为有两个或两个以上星号，如/**。

Answer 2

我从mozilla中找到了一个旧的关于jsdoc编译器的链接，它有下面的行：

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

因此，看起来每行的星号都不是必须的，正如@ McKay博士所说的那样，星号仅用于布局(如果仍然在使用，或者是当前jsdoc的基础)。