星号是否对“有效"有效?JSDoc? [英] Are the asterisk's necessary for "valid" JSDoc?
问题描述
我总是看过以下格式的JSDoc(及其之前的JavaDoc):
/***这是一些JSDoc ...* ...还有更多*/函数foo(){ 但是，我的一位同事不希望没有星号，即:
/**这是一些JSDoc ......还有更多*/函数foo(){ 当我在Eclipse中尝试此操作时，它仍会将代码识别为JSDoc(它的颜色与非JSDoc注释的颜色不同).但是，当我查看JSDoc网站时，所有示例都包括星号...但是，同样地，我也找不到任何说明它们是必需的内容(说实话，JSDoc网站似乎有点可怕)./p>
因此，考虑到我什至找不到关于JSDoc是/不是的正确规范，我想问一下Stack Overflow.在座的任何人都可以指向我:
A)某种规范性的引用(例如，来自JSDoc网站的内容)表示不需要初始星号
B)没有初始星号的示例会出现问题(例如除非拥有初始星号，否则您不能使用很棒的JSDoc库X")
* EDIT *
请澄清一下，我们目前不使用JSDoc文档生成器.这个问题更多来自于希望以行业标准的方式来格式化我们的评论，以及(在将来的某一天)能够使用依赖于JSDoc标准的工具(例如JSDOc documentaiton生成器)的渴望.
基本上，我不太在乎我的同事如何格式化他的JSDoc，我只是不希望非标准的实践将来会引起问题(如果将来存在此类问题，我会希望能够向他解释这一点，而不仅仅是说我不喜欢您格式化JSDoc的方式".
没有行业标准" jsdoc格式.有 jsdoc 3 以某种方式起作用，还有 jsdoc 1 但我不知道人们在生产中静止使用它的案例.然后，有一些工具或多或少成功地尝试了jsdoc的标记.
行首的星号是可选的，通常是正确的，但并非在所有情况下都是正确的.例如，如果将jsdoc 3与 Markdown插件一起使用，则:
此外，请确保在文档注释中使用前导星号！.如果您省略前导星号，则JSDoc的代码解析器可能会删除用于Markdown格式化的其他星号.
因此，各种版本的jsdoc都不需要前导星号，但是在某些用例场景中，绝对需要前导星号.(我没有在jsdoc 3的文档中找到直接指出星号是可选的位置.但是，上面的引用暗示它们是可选的.)
不过，在这里提出的问题中，两个代码段均以/* 开头.从jsdoc 1到jsdoc 3的所有版本的jsdoc都要求注释被处理为标记为像这样的/** 开头带有两个或多个星号.
I've always seen JSDoc (and JavaDoc before it) in the following format:
/**
* This is some JSDoc ...
* ... and some more
*/
function foo() {
However, a co-worker of mine would prefer not to have the initial asterisks, ie.:
/**
This is some JSDoc ...
... and some more
*/
function foo() {
When I try this in Eclipse it still recognizes the code as JSDoc (it colors it differently from non-JSDoc comments). However, when I look at the JSDoc website, all the examples include the asterisks ... but then again, I can't find anything that says they're required either (the JSDoc website seems kind of terrible to be honest).
So, given that I can't even find a proper specification of what JSDoc is/is not, I figured I'd ask Stack Overflow. Can anyone here point me to either:
A) some kind of canonical reference (eg. something from the JSDoc site) saying that the initial asterisks are/are not required
B) examples of where not having the initial asterisks would be problematic (eg. "you can't use cool JSDoc library X unless you have initial asterisks")
*EDIT*
Just to clarify, we don't currently use the JSDoc documentation generator. This question comes more from a desire to format our comments in an industry-standard way, and a desire to (someday in the future) be able to use tools that rely on the JSDoc standard (such as the JSDOc documentaiton generator).
Basically I don't really care how my co-worker formats his JSDoc, I just don't want a non-standard practice to cause a problem in the future (and if there is such a problem in our future, I'd like to be able to explain it to him and not just say "I don't like the way you format your JSDoc").
There is no such thing as an "industry-standard" jsdoc format. There's jsdoc 3 which works in a certain way, and there's jsdoc 2 which works in a similar but different way. There's a jsdoc 1 but I don't know any case of people still using it in production. Then there are tools that try to work jsdoc's markup, more or less successfully.
That the asterisks at the beginning of lines have been optional is generally true but is not true in all cases. For instance, if using jsdoc 3 with a Markdown plugin, then:
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.
So the various versions of jsdoc have not required the leading asterisks but there are some use-case scenarios where the leading asterisks are absolutely required. (I've not found a location in jsdoc 3's documentation that straightforwardly states that the asterisks are optional. The quote above, however, implies that they are.)
One thing though, in the question asked here both code snippets begin with /*. All versions of jsdoc, form jsdoc 1 to jsdoc 3 require comments meant to be processed as jsdoc comments to be marked with two or more asterisks at the start like this /**.
这篇关于星号是否对“有效"有效?JSDoc?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
