Omitting * breaks formatting in VS Code

[LinusU]

• Don't prefix lines with *.

Opening this since I haven't seen this style used elsewhere, and it's breaking VS Code. Closing this issue with "it's a VS Code issue" is absolutely okay 👌

When not prefixing lines with *, all empty lines get's stripped in the @example. It also doesn't highlight the @example block in the source code.

☝️ With * prefix, notice the @example code being red, and that the popup that shows the function help has line breaks at the correct places.

👇 Without * prefix, notice that the @example has the same green color as any other comment, and that the empty lines are stripped in the help popup.

edit: looking at the TSDoc and JSDoc repo/website, I can't find anything that says specifically that you must have them. But I also haven't found a single example that omits them 🤔

edit2: It also breaks syntax highlighting when e.g. describing params:

[sindresorhus]

VS Code has a lot of quirks when it comes to rendering doc comments. Hopefully one day they will switch to use https://github.com/microsoft/tsdoc (when it's more mature). TSDoc seems to handle missing * just fine: https://microsoft.github.io/tsdoc/ (try it there).

I would recommend opening an issue on VS Code. I have no intention to switch back to using *-prefixed lines.

[LinusU]

Will open issue against VS Code 👍