fix(2632): allow missing names in jsdoc param tags

Author: a-tarasyuk

internal/parser/jsdoc.go

@@ -383,7 +383,7 @@ func (p *Parser) parseTag(tags []*ast.Node, margin int) *ast.Node {
 	start := p.scanner.TokenStart()
 	p.nextTokenJSDoc()
 
-	tagName := p.parseJSDocIdentifierName(nil)
+	tagName := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 	indentText := p.skipWhitespaceOrAsterisk()
 
 	var tag *ast.Node
@@ -670,15 +670,15 @@ func (p *Parser) tryParseTypeExpression() *ast.Node {
 	}
 }
 
-func (p *Parser) parseBracketNameInPropertyAndParamTag() (name *ast.EntityName, isBracketed bool) {
+func (p *Parser) parseBracketNameInPropertyAndParamTag(target propertyLikeParse) (name *ast.EntityName, isBracketed bool) {
 	// Looking for something like '[foo]', 'foo', '[foo.bar]' or 'foo.bar'
 	isBracketed = p.parseOptionalJsdoc(ast.KindOpenBracketToken)
 	if isBracketed {
 		p.skipWhitespace()
 	}
 	// a markdown-quoted name: `arg` is not legal jsdoc, but occurs in the wild
 	isBackquoted := p.parseOptionalJsdoc(ast.KindBacktickToken)
-	name = p.parseJSDocEntityName()
+	name = p.parseJSDocEntityName(core.IfElse(target == propertyLikeParseParameter, nil, diagnostics.Identifier_expected))
 	if isBackquoted {
 		p.parseExpectedTokenJSDoc(ast.KindBacktickToken)
 	}
@@ -715,7 +715,7 @@ func (p *Parser) parseParameterOrPropertyTag(start int, tagName *ast.IdentifierN
 	isNameFirst := typeExpression == nil
 	p.skipWhitespaceOrAsterisk()
 
-	name, isBracketed := p.parseBracketNameInPropertyAndParamTag()
+	name, isBracketed := p.parseBracketNameInPropertyAndParamTag(target)
 	indentText := p.skipWhitespaceOrAsterisk()
 
 	if isNameFirst && p.lookAhead(func(p *Parser) bool { _, ok := p.parseJSDocLinkPrefix(); return !ok }) {
@@ -846,9 +846,9 @@ func (p *Parser) parseExpressionWithTypeArgumentsForAugments() *ast.Node {
 
 func (p *Parser) parsePropertyAccessEntityNameExpression() *ast.Node {
 	pos := p.nodePos()
-	node := p.parseJSDocIdentifierName(nil)
+	node := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 	for p.parseOptional(ast.KindDotToken) {
-		name := p.parseJSDocIdentifierName(nil)
+		name := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 		node = p.finishNode(p.factory.NewPropertyAccessExpression(node, nil, name, ast.NodeFlagsNone), pos)
 	}
 	return node
@@ -868,7 +868,7 @@ func (p *Parser) parseThisTag(start int, tagName *ast.IdentifierNode, margin int
 func (p *Parser) parseTypedefTag(start int, tagName *ast.IdentifierNode, indent int, indentText string) *ast.Node {
 	typeExpression := p.tryParseTypeExpression()
 	p.skipWhitespaceOrAsterisk()
-	fullName := p.parseJSDocIdentifierName(nil)
+	fullName := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 	p.skipWhitespace()
 	comment := p.parseTagComments(indent, nil)
 
@@ -984,7 +984,7 @@ func (p *Parser) parseJSDocSignature(start int, indent int) *ast.Node {
 }
 
 func (p *Parser) parseCallbackTag(start int, tagName *ast.IdentifierNode, indent int, indentText string) *ast.Node {
-	fullName := p.parseJSDocIdentifierName(nil)
+	fullName := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 	p.skipWhitespace()
 	comment := p.parseTagComments(indent, nil)
 	typeExpression := p.parseJSDocSignature(p.nodePos(), indent)
@@ -1071,7 +1071,7 @@ func (p *Parser) tryParseChildTag(target propertyLikeParse, indent int) *ast.Nod
 	start := p.scanner.TokenFullStart()
 	p.nextTokenJSDoc()
 
-	tagName := p.parseJSDocIdentifierName(nil)
+	tagName := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 	indentText := p.skipWhitespaceOrAsterisk()
 	var t propertyLikeParse
 	switch tagName.Text() {
@@ -1164,16 +1164,16 @@ func (p *Parser) parseOptionalJsdoc(t ast.Kind) bool {
 	return false
 }
 
-func (p *Parser) parseJSDocEntityName() *ast.EntityName {
-	var entity *ast.EntityName = p.parseJSDocIdentifierName(nil)
+func (p *Parser) parseJSDocEntityName(diagnosticMessage *diagnostics.Message) *ast.EntityName {
+	var entity *ast.EntityName = p.parseJSDocIdentifierName(diagnosticMessage)
 	if p.parseOptional(ast.KindOpenBracketToken) {
 		p.parseExpected(ast.KindCloseBracketToken)
 		// Note that y[] is accepted as an entity name, but the postfix brackets are not saved for checking.
 		// Technically usejsdoc.org requires them for specifying a property of a type equivalent to Array<{ x: ...}>
 		// but it's not worth it to enforce that restriction.
 	}
 	for p.parseOptional(ast.KindDotToken) {
-		name := p.parseJSDocIdentifierName(nil)
+		name := p.parseJSDocIdentifierName(diagnostics.Identifier_expected)
 		if p.parseOptional(ast.KindOpenBracketToken) {
 			p.parseExpected(ast.KindCloseBracketToken)
 		}
@@ -1189,8 +1189,6 @@ func (p *Parser) parseJSDocIdentifierName(diagnosticMessage *diagnostics.Message
 			p.parseErrorAtCurrentToken(diagnosticMessage)
 		} else if isReservedWord(p.token) {
 			p.parseErrorAtCurrentToken(diagnostics.Identifier_expected_0_is_a_reserved_word_that_cannot_be_used_here, p.scanner.TokenText())
-		} else {
-			p.parseErrorAtCurrentToken(diagnostics.Identifier_expected)
 		}
 		return p.finishNode(p.newIdentifier(""), p.nodePos())
 	}

internal/parser/reparser.go

@@ -585,7 +585,8 @@ func findMatchingParameter(fun *ast.Node, parameterTag *ast.JSDocParameterTag, j
 	}
 	for parameterIndex, parameter := range fun.Parameters() {
 		if parameter.Name().Kind == ast.KindIdentifier {
-			if parameterTag.Name().Kind == ast.KindIdentifier && parameter.Name().Text() == parameterTag.Name().Text() {
+			if parameterTag.Name().Kind == ast.KindIdentifier &&
+				((parameter.Name().Text() == parameterTag.Name().Text()) || (parameterIndex == tagIndex && len(parameterTag.Name().Text()) == 0)) {
 				return parameter.AsParameterDeclaration(), true
 			}
 		} else if parameterIndex == tagIndex {

testdata/baselines/reference/conformance/jsdocParamTagNoName.errors.txt

@@ -0,0 +1,13 @@
+a.js(5,14): error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.
+
+
+==== a.js (1 errors) ====
+    /**
+     * @param {(x: string) => string}
+     */
+    function foo(f) {
+        return f(123);
+                 ~~~
+!!! error TS2345: Argument of type 'number' is not assignable to parameter of type 'string'.
+    }
+    

testdata/baselines/reference/conformance/jsdocParamTagNoName.symbols

@@ -0,0 +1,14 @@
+//// [tests/cases/conformance/jsdoc/jsdocParamTagNoName.ts] ////
+
+=== a.js ===
+/**
+ * @param {(x: string) => string}
+ */
+function foo(f) {
+>foo : Symbol(foo, Decl(a.js, 0, 0))
+>f : Symbol(f, Decl(a.js, 3, 13))
+
+    return f(123);
+>f : Symbol(f, Decl(a.js, 3, 13))
+}
+

testdata/baselines/reference/conformance/jsdocParamTagNoName.types

@@ -0,0 +1,16 @@
+//// [tests/cases/conformance/jsdoc/jsdocParamTagNoName.ts] ////
+
+=== a.js ===
+/**
+ * @param {(x: string) => string}
+ */
+function foo(f) {
+>foo : (f: (x: string) => string) => string
+>f : (x: string) => string
+
+    return f(123);
+>f(123) : string
+>f : (x: string) => string
+>123 : 123
+}
+

testdata/baselines/reference/submodule/conformance/jsDeclarationsMissingTypeParameters.js

@@ -49,7 +49,7 @@ function w() { return null; }
 declare function x(y?: Array | undefined): void;
 /** @param {function (Array)} func Invoked
  */
-declare function y(func: any): void;
+declare function y(func: function): void;
 /**
  * @return {(Array.<> | null)} list of devices
  */

testdata/baselines/reference/submodule/conformance/jsDeclarationsMissingTypeParameters.js.diff

@@ -9,7 +9,7 @@
  /** @param {function (Array)} func Invoked
   */
 -declare function y(func: (arg0: any[]) => any): void;
-+declare function y(func: any): void;
++declare function y(func: function): void;
  /**
   * @return {(Array.<> | null)} list of devices
   */

testdata/baselines/reference/submodule/conformance/jsDeclarationsMissingTypeParameters.types

@@ -12,8 +12,8 @@ function x(y) { }
 /** @param {function (Array)} func Invoked
  */
 function y(func) { return; }
->y : (func: any) => void
->func : any
+>y : (func: function) => void
+>func : function
 
 /**
  * @return {(Array.<> | null)} list of devices

testdata/baselines/reference/submodule/conformance/jsDeclarationsMissingTypeParameters.types.diff

@@ -14,8 +14,8 @@
  function y(func) { return; }
 ->y : (func: (arg0: any[]) => any) => void
 ->func : (arg0: any[]) => any
-+>y : (func: any) => void
-+>func : any
++>y : (func: function) => void
++>func : function
 
  /**
   * @return {(Array.<> | null)} list of devices

testdata/baselines/reference/submodule/conformance/jsDeclarationsRestArgsWithThisTypeInJSDocFunction.errors.txt

@@ -1,10 +1,14 @@
+bug38550.js(3,14): error TS2552: Cannot find name 'function'. Did you mean 'Function'?
 bug38550.js(3,22): error TS1005: '}' expected.
 
 
-==== bug38550.js (1 errors) ====
+==== bug38550.js (2 errors) ====
     export class Clazz {
       /**
        * @param {function(this:Object, ...*):*} functionDeclaration
+                 ~~~~~~~~
+!!! error TS2552: Cannot find name 'function'. Did you mean 'Function'?
+!!! related TS2728 lib.es5.d.ts:--:--: 'Function' is declared here.
                          ~
 !!! error TS1005: '}' expected.
        */