Asterisk seems to be treated specially in documentation preview

[ramya-rao-a]

From @jawnsy on January 29, 2018 17:43

Description

Documentation preview requires an asterisk to be escaped, while godoc does not require the escaping. This is a pretty minor issue but I'd expect vscode-go to behave as close to godoc as possible.

Actual behavior

This comment:

// ValidFileName returns nil if the string is a valid file name, or an
// error otherwise. If pattern is true, file glob patterns are permitted
// ("*" and "?", e.g. "abc*")

is rendered like so:

Notice that the * is missing between "".

Expected behavior

godoc -http renders it like so:

I'd expect this to be correct, though I haven't read godoc spec.

Workaround

You can escape the * in the comment (\*), like so:

// ValidFileName returns nil if the string is a valid file name, or an
// error otherwise. If pattern is true, file glob patterns are permitted
// ("\*" and "?", e.g. "abc*")

Then it appears to be rendered as expected:

Version info

vscode-go 0.6.73

VSCode version info (OS: Windows 10):

Version 1.19.2
Commit 490ef761b76b3f3b3832eff7a588aac891e5fe80
Date 2018-01-10T15:55:03.538Z
Shell 1.7.9
Renderer 58.0.3029.110
Node 7.9.0
Architecture x64

Copied from original issue: microsoft/vscode-go#1486

[ramya-rao-a]

Thanks for reporting!
Seems to be an issue with VS Code and not the Go extension.
I get similar issues on hover text when using typescript

[ramya-rao-a]

[jrieken]

Seems to be an issue with VS Code and not the Go extension.

@ramya-rao-a Are you saying that you are using MarkdownString#appendText and this still happens?

There are two APIs (old/new). The old is MarkedString and extension authors must manually escape markdown syntax. The new is MarkdownString with some sugar-utils to append text as text or markdown.

[ramya-rao-a]

For Go, I am using the old MarkedString, I can give the new one a try.
My screenshots in #42353 (comment) are for typescript. @mjbvz What do you use there?

[mjbvz]

We support markdown content in JSDocs so we don’t escape anything. The * is probably being treated as the start of italics. Can you escape the * manually in the doc?

[ramya-rao-a]

@mjbvz Thats right. The text between the 2 * is being treated as italics in typescript.

So what's the expectation here?
We cant expect code owners to escape the * all the time

[jawnsy]

The expectations might be different between JavaScript/TypeScript/JSDoc and Go/godoc.

I'd expect JSDoc to render markdown content if the Markdown plugin is configured, but not otherwise. In other words, I'd expect the preview to be as close as possible to what I'd see in generated HTML. The current behavior doesn't seem to check the configuration before rendering?

godoc doesn't seem to support Markdown as far as I can tell, so it shouldn't be rendered in VSCode either.

[mjbvz]

@ramya-rao-a No good solution. Either you convert your jsdocs to markdown or we disable markdown everywhere. I don't think we can detect when a jsdoc comment should or shouldn't be markdown (although if you surround the * with spaces, I don't think it will be treated as an italic marker)

[ramya-rao-a]

@mjbvz Anyway I can tell the hoverprovider to treat given content as just string and not markdown?

[mjbvz]

@ramya-rao-a In general, or for a given jsdoc?

[mjbvz]

Closing this as-designed for jsdocs. No good solution without breaking jsdocs that do want to use markdown.

Workaround is to escape any special markdown characters, such as \*