我一直看到以下格式的 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 文档生成器)的愿望。
基本上我真的不在乎我的同事如何格式化他的 JSDoc，我只是不希望非标准的做法在未来造成问题(如果我们 future 有这样的问题，我我希望能够向他解释，而不仅仅是说“我不喜欢你格式化 JSDoc 的方式”)。
最佳答案
没有所谓的“行业标准”jsdoc 格式。有 jsdoc 3它以某种方式工作，并且有jsdoc 2它以相似但不同的方式工作。有一个 jsdoc 1但我不知道有人仍然在生产中使用它。然后有一些工具尝试处理 jsdoc 的标记，或多或少地成功了。
行首的星号是可选的，这通常是正确的，但并非在所有情况下都是正确的。例如，如果将 jsdoc 3 与 Markdown plugin 一起使用，然后:
Also, be sure to use leading asterisks in your doc comments! If you omit the leading asterisks, JSDoc's code parser may remove other asterisks that are used for Markdown formatting.
所以 jsdoc 的各种版本都不需要前导星号，但有一些用例场景绝对需要前导星号。 (我在 jsdoc 3 的文档中没有找到直接说明星号 是可选的位置。但是，上面的引用暗示它们是。)
但有一件事，在此处提出的问题中，两个代码片段都以 /* 开头。 jsdoc 的所有版本，从 jsdoc 1 到 jsdoc 3，都需要将要作为 jsdoc 注释处理的注释标记为 with two or more asterisks。像这样开始 /**.
关于jsdoc - "valid"JSDoc 是否需要星号？，我们在Stack Overflow上找到一个类似的问题： https://stackoverflow.com/questions/22465878/