Distinguish doc-comments from other comments

[erights]

https://github.com/airbnb/javascript#comments--multiline
recommend /** ... */ without even mentioning /* ... */. The former should only be used for doc-comments. The latter should be used for all comments that are not doc-comments, even if they are multiline.

[ljharb]

I'm not sure I understand; what our guide requires is to use /* */ for any multiline comment, full stop.

[erights]

Look at the example comment.

…

On Dec 25, 2017 1:24 PM, "Jordan Harband" ***@***.***> wrote: I'm not sure I understand; what our guide requires is to use /* */ for any multiline comment, full stop. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#1679 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAQtzO44MUeVtb6ZWlafdsjjRErzg1Ciks5tD-h1gaJpZM4RMWFb> .

[ljharb]

The first one is marked "bad" (because it uses // and is multiline), the second one is marked "good" (because it uses /* and is multiline).

[gergoerdosi]

@ljharb: Created a PR to illustrate the issue @erights mentioned.

[ljharb]

I still don’t understand. Two stars should be used in any and all multiline comment beginnings.

[gergoerdosi]

Then maybe it's something else, let's hear from @erights. Closed the PR.

[ljharb]

I’m also not sure what a “doc-comment” is - do you mean JSDoc? We more or less ban JSDoc entirely; we just haven’t put it in the guide yet, so i wouldn’t want to call them out specifically here.

[erights]

Why does your example comment begin with "/**" rather than "/*"?

[ljharb]

The extra * is intentionally required so all the *s can be aligned, as in the "good" examples.

[erights]

/*
 * make() returns a new element
 * based on the passed-in tag name
 */

aligns the *s without beginning with a /**.

[ljharb]

Then the inner stars are only indented by one space, instead of two.

However, i do think i see what you mean - the “good” example doesn’t do this alignment. I’ll clean up this section.