Description
- VSCode Version: Code 1.14.0 (b8cd5b9, 2017-07-10T18:36:31.751Z)
- OS Version: Windows_NT ia32 10.0.15063
- Extensions:
Extension | Author (truncated) | Version |
---|---|---|
intellij-idea-keybindings | k-- | 0.2.12 |
cpptools | ms- | 0.12.1 |
Steps to Reproduce:
- Write a Jsdoc comment such as
/** This is a JSDoc comment
* <ul>
* <li> First Item </li>
* <li> Second Item </li>
* </ul>
* @description <p> Description tags are supposed to support HTML formatting </p>
* @constructor
* @param {Streamer} in_stream - (Optional) An "inbound" stream with data to be read.
*/
- Mouse over the class/object/variable you tried to document and see that everything is rendered as plain text.
VSCode will display JSDoc comments as documentation on mouseover, however with it rendering any html markup as plaintext, comments that would normally display with orderly lists, line breaks, and paragraphs is all mashed together in a cluttered mess with no new lines.
For example the Jsdoc in the first step renders as:
Creates a Header
<ul><li> First Item </li><li> Second Item </li></ul>
@description <p> Description tags are supposed to support HTML formatting </p>
@constructor
@param {Streamer} in_stream - (Optional) An "inbound" stream with data to be read.
I did notice that if you do this:
/** Blah blah blah
*
* Own Line
*
* Another Line
*/
VsCode will render this as:
Blah blah blah
Own Line
Another Line
when you mouseover the documented item. Note that to get "Own Line" and "Another Line" on their own lines, it took an extra blank line.
Please do not render html tags in comments, or at least treat </br>, <p>
etc. as new lines so that there is some semblance of formatting being applied to displayed documentation. Writing jsdoc comments that are intended to render nicely in VSCode require an inordinate amount of wasted lines just to accomplish what a<p>
or </br>
would accomplish on the same line.
With how things are now you have to pick between displaying Jsdoc documentation nicely in HTML, or have it readable in VScode, you can't have both without one or the other being poorly formatted if not unreadable.
Reproduces without extensions: Yes/No