Are the asterisk's necessary for "valid" JSDoc?

Question

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").

Answer 1

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 /**.

Answer 2

I found this old link about jsdoc compiler from mozilla, that has the following line int it:

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

So it looks like the asterisk at every line are not mandtory and as @Dr. McKay says are only for the layout (if this is still in use or is the base for the current jsdoc).