[JavaScript] Handle type argument in JSDoc documentation

JavaScript/JavaScript.sublime-syntax

@@ -106,6 +106,8 @@ variables:
 
  # '@' followed by a pattern like \S but excluding literal '*' and '@'.
  jsdoc_block_tag: \@[^\n\t\f\v *@]+
+ # Tags that are optionally followed by a type expression.
+ jsdoc_block_tag_with_type: \@(?:arg(?:ument)?|param|typedef|type|returns?|prop(?:erty)?|enum|implements|member|module|namespace|private|protected|template|this|throws|exception|yields?|var)\b
 
 contexts:
  main:
@@ -164,12 +166,58 @@ contexts:
  push: jsdoc-block-tag
 
  jsdoc-block-tag:
+ - match: '{{jsdoc_block_tag_with_type}}'
+ scope: entity.other.attribute-name.documentation.js
+ set:
+ - match: '\s+(?=\{)'
+ set: jsdoc-type-expression
+ - match: ''
+ pop: 1
  - match: '{{jsdoc_block_tag}}'
  scope: entity.other.attribute-name.documentation.js
  pop: 1
  - match: (?=\S)|$
  pop: 1
 
+ jsdoc-type-expression:
+ - match: '\{'
+ scope: punctuation.definition.type.begin.js, meta.tag.jsdoc
+ set:
+ - match: '\}'
+ scope: meta.tag.jsdoc punctuation.definition.type.end.js
+ pop: 1
+ - include: jsdoc-type-expression-body
+
+ jsdoc-type-expression-body:
+ - match: (?=\*/)
+ pop: 1
+ - match: '^\s*(\*)'
+ captures:
+ 1: punctuation.definition.comment.js
+ - match: \.
+ scope: meta.type.js punctuation.accessor.dot.js
+ - match: '\{'
+ scope: meta.type.js
+ push: jsdoc-type-expression-body-nested
+ - match: |-
+ (?x:
+ (?! # break on patterns handled explicitly above
+ \*\/|
+ ^\s*\*|
+ \}|
+ \{|
+ \.
+ ).
+ # consume as many consecutive characters as possible to not break the ligatures
+ )*
+ scope: meta.type.js
+
+ jsdoc-type-expression-body-nested:
+ - match: '\}'
+ scope: meta.type.js
+ pop: 1
+ - include: jsdoc-type-expression-body
+
  line-comments:
  - match: /{4,}
  scope: punctuation.definition.comment.js

JavaScript/tests/syntax_test_js_jsdoc.js

@@ -40,3 +40,47 @@
 /*@a */
 //^^ - entity.other.attribute-name.documentation
 // ^^ punctuation.definition.comment.end
+
+/** @type {string[]} */
+// ^^^^^^^^ meta.type
+// ^^^^ - meta.type
+// ^ punctuation.definition.type.begin
+// ^ punctuation.definition.type.end
+
+/** @type {import('fs').FSWatcher} */
+// ^^^^^^^^^^^^^^^^^^^^^^ meta.type
+// ^^^^ - meta.type
+// ^ punctuation.accessor.dot
+// ^ punctuation.definition.type.end
+
+ /**
+ * @param {{
+// ^ meta.type
+// ^ comment.block.documentation punctuation.definition.comment
+ * foo: A.B
+// ^ comment.block.documentation punctuation.definition.comment
+//^^ - meta.type
+// ^^^^^^^^^^^ meta.type
+// ^ punctuation.accessor.dot
+ * }} foo
+// ^^ meta.type
+// ^^^^^ - meta.type
+ *
+// ^ comment.block.documentation punctuation.definition.comment
+ */
+
+/** @type{string} */
+// ^^^^^^^^ - meta.type
+
+/** @type {string */
+// ^^^^^^^ meta.type
+// ^^ punctuation.definition.comment.end - meta.type
+
+/** @type {{foo: number */
+// ^^^^^^^^^^^^^ meta.type
+// ^^ punctuation.definition.comment.end - meta.type
+
+// Mostly just for visual inspection to ensure that ligatures are not broken.
+/** @type {p: number => string} */
+// ^^^^^^^^^^^^^^^^^^^ meta.type
+// ^^ punctuation.definition.comment.end - meta.type