"有效"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 Overflow.这里的任何人都可以指出:

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

B)没有初始星号的例子会有问题(例如"你不能使用酷的JSDoc库X,除非你有初始的星号")

*编辑*

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

基本上我并不关心我的同事如何格式化他的JSDoc,我只是不希望非标准的练习在将来引起问题(如果我们将来有这样的问题,我会喜欢能够向他解释而不只是说"我不喜欢你格式化JSDoc的方式".

Answer 1

没有"行业标准"的jsdoc格式.有jsdoc 3以某种方式工作,并且有jsdoc 2以类似但不同的方式工作.有一个jsdoc 1,但我不知道任何人仍然在生产中使用它.然后有一些工具尝试使用jsdoc的标记,或多或少成功.

线条开头的星号是可选的通常是正确的,但并非在所有情况下都是如此.例如,如果将jsdoc 3与Markdown插件一起使用,则:

另外,请务必在文档评论中使用前导星号!如果省略前导星号,JSDoc的代码解析器可能会删除用于Markdown格式的其他星号.

所以各种版本的jsdoc都不需要领先的星号,但是有一些用例场景,绝对需要使用主要的星号.(我没有在jsdoc 3的文档中找到一个直接声明星号是可选的位置.但是,上面的引用暗示它们是.)

但有一点,在这里提出的问题中,两个代码片段都以此开头/*.所有版本的jsdoc,从jsdoc 1到jsdoc 3都需要注释,这些注释要作为jsdoc注释处理,并在开头标记两个或多个星号,如下所示/**.