This will mark the entire jsdoc comment as meta.embeded.js which I don't think is correct. The intention of the original pr was to only mark the jsdoc type annotations as meta.embedded

@mjbvz How does this hinder VSCode's ability to distinguish embedded documentation from comment text?

When TypeScript or any other suggestion provider does not return any results, we default to showing a set of word based suggestions. Many users found this annoying when typing out strings or comments, so we disable them in these scopes. In the case of jsdocs, we want re-enable quick suggestions but only in the code (type) part of comments, not in entire comment body.

We also have very limited information when we decide whether or not to enable quick suggestions. All we know is if are we are in a string, a comment, or regular code. We would not be able to know that we are in a entity.name.type.instance.jsdoc scope for example. That's where meta.embedded comes into play. It resets the basic scope info so that even if the meta embedded span is inside a string or comment, it is marked a regular code

I'm still failing to see a problem here...

Are you saying this only works when meta.embedded is scoped at the same level as everything else?

My point is that meta.embedded should only apply to the specific spans within a jsdoc comment that contain type annotations .

Take this example code with some toy token spans:

/** @param {string} x Desc */ function(x) {
|--a------------------------| |--d-----...
   |-b--------------------|
          |-c-----| 

We want quick suggestions to be enabled:

• Always
  • Except in comments
    • Unless the area within the comment is actually a jsdoc type

That means we want quick suggestions to be enabled only in spans c and d.

My proposed scopes for each span:

a:
- comment.jsdoc
- source.js

b:
- comment.jsdoc
- source.js

c:
- jsdoc.type
- meta.embedded
- comment.jsdoc
- source.js

d:
- source.js

This scoping allows us to correctly enable quick suggestions only spans c and d using the simple rules:

• Always enable quick suggestions
  • Unless the cursor is in a comment span (marked by a comment. scope)
    • Except for cases where the cursor is also in a meta.emedded span

This change on the other hand does:

a:
- comment.jsdoc
- source.js

b:
- meta.embedded
- comment.jsdoc
- source.js

c:
- jsdoc.type
- meta.embedded
- comment.jsdoc
- source.js

d:
- source.js

Which following our logic would enable quick suggestions in b, c, and d

That feels like it's going too far, IMO. Every other grammar that embeds other grammars does so with meta.embedded scoped from start to end. Limiting the scope in this way feels inconsistent and illogical.

Personally, I think this is more an issue with VSCode's implementation of quick suggestions...

I'm struggling to understand the opposition to the first PR. The JSdoc type annotations are spans of a language embedded within a comment.

We went with the meta embedded approach in the first place because using the very simple set of rules outlined, we can support a large number of scenarios. The core engine does not need to know anything language specific, only that comment scopes mark a comment within code, and that meta.embedded scopes mark a new embedded language which also overrides any previous comment scopes

The JSdoc type annotations are spans of a language embedded within a comment.

Technically, JSDoc is everything in between those spans, too. You appear to be thinking of it like this:

- /**                                Comment
-  * Function description            Comment
+ * @param {String} name             JSDoc
-  *     Parameter description       Comment
+ * @return {Object}                 JSDoc
-  *     Return value's description  Comment
- */                                Comment

Whereas it's actually closer to this:

- /**                                Comment
+ * Function description             JSDoc
+ * @param {String} name               │
+ *     Parameter description          │
+ * @return {Object}                   │
+ *     Return value's description   JSDoc
- */                                Comment

and that meta.embedded scopes mark a new embedded language which also overrides any previous comment scopes

Erm, which is what this PR is doing...

Please see my example. I have always been talking specifically about the type annotation within the jsdoc, not the entire jsdoc

I see what you mean, but this still feels uncomfortably hacky to me. 😕

@50Wliu, what do you recommend?

@50Wliu do you have any thoughts on this?

@50Wliu Feel free to merge this if you think it is useful.