Skip to content

JsDoc markup ignored/displayed as plain text #31161

Closed
@Gochida

Description

@Gochida
  • 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:

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

Metadata

Metadata

Assignees

Labels

*as-designedDescribed behavior is as designedjavascriptJavaScript support issues

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions