Permit URLs in @see tags and make links for name references (#2359)

Author: ahejlsberg

internal/ls/hover.go

@@ -99,8 +99,6 @@ func (l *LanguageService) getDocumentationFromDeclaration(c *checker.Checker, de
 						writeOptionalEntityName(&b, tag.Name())
 					case ast.KindJSDocAugmentsTag:
 						writeOptionalEntityName(&b, tag.ClassName())
-					case ast.KindJSDocSeeTag:
-						writeOptionalEntityName(&b, tag.AsJSDocSeeTag().NameExpression)
 					case ast.KindJSDocTemplateTag:
 						for i, tp := range tag.TypeParameters() {
 							if i != 0 {
@@ -119,6 +117,13 @@ func (l *LanguageService) getDocumentationFromDeclaration(c *checker.Checker, de
 						} else {
 							writeCode(&b, "tsx", commentText)
 						}
+					} else if tag.Kind == ast.KindJSDocSeeTag && tag.AsJSDocSeeTag().NameExpression != nil {
+						b.WriteString(" — ")
+						l.writeNameLink(&b, c, tag.AsJSDocSeeTag().NameExpression.Name(), "", false /*quote*/, isMarkdown)
+						if len(comments) != 0 {
+							b.WriteString(" ")
+							l.writeComments(&b, c, comments, isMarkdown)
+						}
 					} else if len(comments) != 0 {
 						b.WriteString(" ")
 						if !commentHasPrefix(comments, "-") {
@@ -550,6 +555,10 @@ func (l *LanguageService) writeJSDocLink(b *strings.Builder, c *checker.Checker,
 		}
 		return
 	}
+	l.writeNameLink(b, c, name, text, quote, isMarkdown)
+}
+
+func (l *LanguageService) writeNameLink(b *strings.Builder, c *checker.Checker, name *ast.Node, text string, quote bool, isMarkdown bool) {
 	declarations := getDeclarationsFromLocation(c, name)
 	if len(declarations) != 0 {
 		declaration := declarations[0]
@@ -569,7 +578,7 @@ func (l *LanguageService) writeJSDocLink(b *strings.Builder, c *checker.Checker,
 		}
 		return
 	}
-	writeQuotedString(b, getEntityNameString(name)+" "+text, quote && isMarkdown)
+	writeQuotedString(b, getEntityNameString(name)+core.IfElse(len(text) != 0, " ", "")+text, quote && isMarkdown)
 }
 
 func trimCommentPrefix(text string) string {

internal/parser/jsdoc.go

@@ -89,17 +89,12 @@ func (p *Parser) parseJSDocTypeExpression(mayOmitBraces bool) *ast.Node {
 func (p *Parser) parseJSDocNameReference() *ast.Node {
 	pos := p.nodePos()
 	hasBrace := p.parseOptional(ast.KindOpenBraceToken)
-	p2 := p.nodePos()
-	entityName := p.parseEntityName(false, nil)
-	for p.token == ast.KindPrivateIdentifier {
-		p.scanner.ReScanHashToken() // rescan #id as # id
-		p.nextTokenJSDoc()          // then skip the #
-		entityName = p.finishNode(p.factory.NewQualifiedName(entityName, p.parseIdentifier()), p2)
-	}
+	entityName := p.parseJSDocLinkName()
 	if hasBrace {
 		p.parseExpectedJSDoc(ast.KindCloseBraceToken)
 	}
-
+	p.scanner.ResetPos(p.scanner.TokenFullStart())
+	p.nextTokenJSDoc()
 	return p.finishNode(p.factory.NewJSDocNameReference(entityName), pos)
 }
 
@@ -627,7 +622,6 @@ func (p *Parser) parseJSDocLink(start int) *ast.Node {
 func (p *Parser) parseJSDocLinkName() *ast.Node {
 	if tokenIsIdentifierOrKeyword(p.token) {
 		pos := p.nodePos()
-
 		name := p.parseIdentifierName()
 		for p.parseOptional(ast.KindDotToken) {
 			var right *ast.IdentifierNode
@@ -638,7 +632,6 @@ func (p *Parser) parseJSDocLinkName() *ast.Node {
 			}
 			name = p.finishNode(p.factory.NewQualifiedName(name, right), pos)
 		}
-
 		for p.token == ast.KindPrivateIdentifier {
 			p.scanner.ReScanHashToken()
 			p.nextTokenJSDoc()
@@ -794,11 +787,10 @@ func (p *Parser) parseTypeTag(previousTags []*ast.Node, start int, tagName *ast.
 }
 
 func (p *Parser) parseSeeTag(start int, tagName *ast.IdentifierNode, indent int, indentText string) *ast.Node {
-	isMarkdownOrJSDocLink := p.token == ast.KindOpenBracketToken || p.lookAhead(func(p *Parser) bool {
-		return p.nextTokenJSDoc() == ast.KindAtToken && tokenIsIdentifierOrKeyword(p.nextTokenJSDoc()) && isJSDocLinkTag(p.scanner.TokenValue())
-	})
+	hasNameReference := p.isIdentifier() && !strings.HasPrefix(p.sourceText[p.scanner.TokenEnd():], "://") ||
+		p.token == ast.KindOpenBraceToken && p.lookAhead((*Parser).nextTokenIsIdentifierOrKeyword)
 	var nameExpression *ast.Node
-	if !isMarkdownOrJSDocLink {
+	if hasNameReference {
 		nameExpression = p.parseJSDocNameReference()
 	}
 	comments := p.parseTrailingTagComments(start, p.nodePos(), indent, indentText)

testdata/baselines/reference/fourslash/quickInfo/quickInfoForJSDocWithHttpLinks.baseline

@@ -40,7 +40,7 @@
 // | ```
 // | 
 // | 
-// | *@see* `https` — ://hvad 
+// | *@see* — https://hvad 
 // | ----------------------------------------------------------------------
 // 
 // /** @see {@link https://hva} */
@@ -159,7 +159,7 @@
     "item": {
       "contents": {
         "kind": "markdown",
-        "value": "```tsx\nvar see1: boolean\n```\n\n\n*@see* `https` — ://hvad "
+        "value": "```tsx\nvar see1: boolean\n```\n\n\n*@see* — https://hvad "
       },
       "range": {
         "start": {

testdata/baselines/reference/fourslash/quickInfo/quickInfoJsDocTags4.baseline

@@ -26,7 +26,7 @@
 // | *@author* — Me <me@domain.tld>
 // | 
 // | 
-// | *@see* `x` — (the parameter)
+// | *@see* — x (the parameter)
 // | 
 // | 
 // | *@param* `x` - x comment
@@ -56,7 +56,7 @@
     "item": {
       "contents": {
         "kind": "markdown",
-        "value": "```tsx\n(method) Bar.method(x: number, y: number): number\n```\ncomment\n\n*@author* — Me <me@domain.tld>\n\n\n*@see* `x` — (the parameter)\n\n\n*@param* `x` - x comment\n\n\n*@param* `y` - y comment\n\n\n*@returns* — The result\n"
+        "value": "```tsx\n(method) Bar.method(x: number, y: number): number\n```\ncomment\n\n*@author* — Me <me@domain.tld>\n\n\n*@see* — x (the parameter)\n\n\n*@param* `x` - x comment\n\n\n*@param* `y` - y comment\n\n\n*@returns* — The result\n"
       },
       "range": {
         "start": {

testdata/baselines/reference/fourslash/quickInfo/quickInfoJsDocTags5.baseline

@@ -26,7 +26,7 @@
 // | *@author* — Me <me@domain.tld>
 // | 
 // | 
-// | *@see* `x` — (the parameter)
+// | *@see* — x (the parameter)
 // | 
 // | 
 // | *@param* `x` - x comment
@@ -56,7 +56,7 @@
     "item": {
       "contents": {
         "kind": "markdown",
-        "value": "```tsx\n(method) Bar.method(x: any, y: any): number\n```\ncomment\n\n*@author* — Me <me@domain.tld>\n\n\n*@see* `x` — (the parameter)\n\n\n*@param* `x` - x comment\n\n\n*@param* `y` - y comment\n\n\n*@returns* — The result\n"
+        "value": "```tsx\n(method) Bar.method(x: any, y: any): number\n```\ncomment\n\n*@author* — Me <me@domain.tld>\n\n\n*@see* — x (the parameter)\n\n\n*@param* `x` - x comment\n\n\n*@param* `y` - y comment\n\n\n*@returns* — The result\n"
       },
       "range": {
         "start": {