@example breaks when example includes `@` character (org package imports)

[mesqueeb]

TS Template added by @mjbvz

TypeScript Version: 4.0.0-dev.20200701

Search Terms

• jsdoc
• example
• code block
• quick info

---

• VSCode Version:

Version: 1.46.1
Commit: cd9ea6488829f560dc949a8b2fb789f3cdc05f5d
Date: 2020-06-17T21:17:14.222Z (1 wk ago)
Electron: 7.3.1
Chrome: 78.0.3904.130
Node.js: 12.8.1
V8: 7.8.279.23-electron.0
OS: Darwin x64 19.4.0

• OS Version:

macOS 10.15.4 (19E2269)

Steps to Reproduce:

1. hover over a JSDoc with an @example with an @ in the example (eg. an organisation package import)
2. see the error:

As you can see from the screenshot, the whole code @example is broken because it's written require('@google-cloud/storage') inside the example.

Does this issue occur when all extensions are disabled?: Yes

[mjbvz]

Minimal example:

/**
 * @example
 * class Foo {
 *  @bla foo() { }
 * }
 */
function foo() { }

Results in:

[Trace  - 01:04:36.990] <semantic> Response received: quickinfo (513). Request took 2 ms. Success: true 
Result: {
    "kind": "function",
    "kindModifiers": "",
    "start": {
        "line": 7,
        "offset": 10
    },
    "end": {
        "line": 7,
        "offset": 13
    },
    "displayString": "function foo(): void",
    "documentation": "",
    "tags": [
        {
            "name": "example",
            "text": "class Foo {"
        },
        {
            "name": "bla",
            "text": "foo() { }\r}"
        }
    ]
}

[RyanCavanaugh]

@mjbvz What exactly is the proposed behavior change here? This seems fundamentally unsolvable - we have no idea whether @bla is a decorator or a new JS Doc tag (it could easily be a decorator named @param), and parsing @example with a real parser is going to end up "swallowing" a lot of example snippets that aren't brace- or paren-balanced.

[mjbvz]

No proposal at the moment, just moving upstream so we can collect more feedback on the problem

[mesqueeb]

@RyanCavanaugh I think if you can check if there there is any other characters other than * (space - star - space) in front of the @ + the previous tag is a @example one, you'd be able to differentiate them!

What do you think ? : )

It's especially annoying when we use organisation scopes in import statements:

/**
 * @example
 * import { something } from '@my-org/my-package'
 */

Thanks so much!!

[mesqueeb]

@RyanCavanaugh I had another idea! Make it sure VSCode checks any @ tag if it's an existing JSDoc tag or not! If not, and it's behind an @example tag, you're pretty sure it's part of the example!! ;)

This seems fundamentally unsolvable

What do you think about my suggestions, still fundamentally unsolvable? : O