Skip to content

Properly format @example in quick info #2329

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ahejlsberg merged 3 commits into from
Dec 11, 2025
+55 −18
Merged

Properly format @example in quick info #2329

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0081744
Properly format @example in quick info
ahejlsberg Dec 10, 2025
85899fb
Accept new baselines
ahejlsberg Dec 10, 2025
8e06545
Also check for newline in code fence check
ahejlsberg Dec 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions internal/ls/hover.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import (
"github.com/microsoft/typescript-go/internal/collections"
"github.com/microsoft/typescript-go/internal/core"
"github.com/microsoft/typescript-go/internal/lsp/lsproto"
"github.com/microsoft/typescript-go/internal/scanner"
)

const (
Expand Down Expand Up @@ -109,14 +110,19 @@ func (l *LanguageService) getDocumentationFromDeclaration(c *checker.Checker, de
}
}
comments := tag.Comments()
if len(comments) != 0 {
if commentHasPrefix(comments, "```") {
if tag.Kind == ast.KindJSDocTag && tag.TagName().Text() == "example" {
b.WriteString("\n")
commentText := strings.TrimRight(getCommentText(comments), " \t\r\n")
if len(commentText) > 6 && strings.HasPrefix(commentText, "```") && strings.HasSuffix(commentText, "```") && strings.Contains(commentText, "\n") {
b.WriteString(commentText)
b.WriteString("\n")
} else {
b.WriteString(" ")
if !commentHasPrefix(comments, "-") {
b.WriteString("— ")
}
writeCode(&b, "tsx", commentText)
}
} else if len(comments) != 0 {
b.WriteString(" ")
if !commentHasPrefix(comments, "-") {
b.WriteString("— ")
}
l.writeComments(&b, c, comments, isMarkdown)
}
Expand All @@ -127,6 +133,19 @@ func (l *LanguageService) getDocumentationFromDeclaration(c *checker.Checker, de
return b.String()
}

func getCommentText(comments []*ast.Node) string {
var b strings.Builder
for _, comment := range comments {
switch comment.Kind {
case ast.KindJSDocText:
b.WriteString(comment.Text())
case ast.KindJSDocLink, ast.KindJSDocLinkCode, ast.KindJSDocLinkPlain:
b.WriteString(scanner.GetTextOfNode(comment))
}
}
return b.String()
}

func formatQuickInfo(quickInfo string) string {
var b strings.Builder
b.Grow(32)
Expand Down
7 changes: 5 additions & 2 deletions testdata/baselines/reference/fourslash/quickInfo/quickInfoForJSDocCodefence.baseline
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,12 @@
// | ```
// |
// |
// | *@example* — ``
// | *@example*
// | ```tsx
Copy link
Member

@jakebailey jakebailey Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know if this one should work; the old baseline was:

=== /tests/cases/fourslash/quickInfoForJSDocCodefence.ts ===
// /**
//  * @example
//  * ```
//  * 1 + 2
//  * ```
//  */
// function foo() {
//          ^^^
// | ----------------------------------------------------------------------
// | function foo(): string
// | @example ```
// | 1 + 2
// | ```
// | ----------------------------------------------------------------------
//     return '2';
// }
// /**
//  * @example
//  * ``
//  * 1 + 2
//  * `
//  */
// function boo() {
//          ^^^
// | ----------------------------------------------------------------------
// | function boo(): string
// | @example ``
// | 1 + 2
// | `
// | ----------------------------------------------------------------------
//     return '2';
// }

Copy link
Member Author

@ahejlsberg ahejlsberg Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the new baselines look right. Unless the @example text starts and ends with exactly three backticks, we want to put a code fence around it.

Copy link
Member

@jakebailey jakebailey Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess I don't know what the original intent of this weird case was, so it's probably fine.

Technically, one can use an arbitrary number of opening backticks to be able to stick even more backticks into a block, but it's probably okay to ignore that for now

Copy link
Member Author

@ahejlsberg ahejlsberg Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We really just want to recognize code that's already fenced and avoid adding another fence and the current check is fine for that. The writeCode helper function we use to fence an un-fenced block does indeed ensure we use a sufficient number of backticks.

// | ``
// | 1 + 2
// | `
// | ```
// |
// | ----------------------------------------------------------------------
// return '2';
Expand Down Expand Up @@ -84,7 +87,7 @@
"item": {
"contents": {
"kind": "markdown",
"value": "```tsx\nfunction boo(): string\n```\n\n\n*@example* — ``\n1 + 2\n`\n"
"value": "```tsx\nfunction boo(): string\n```\n\n\n*@example*\n```tsx\n``\n1 + 2\n`\n```\n"
},
"range": {
"start": {
Expand Down
35 changes: 25 additions & 10 deletions testdata/baselines/reference/fourslash/quickInfo/quickInfoForJSDocUnknownTag.baseline
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,12 @@
// | ```
// |
// |
// | *@example* — if (true) {
// | *@example*
// | ```tsx
// | if (true) {
// | foo()
// | }
// | ```
// |
// | ----------------------------------------------------------------------
// return '2';
Expand All @@ -35,9 +38,12 @@
// | ```
// |
// |
// | *@example* — {
// | *@example*
// | ```tsx
// | {
// | foo()
// | }
// | ```
// |
// | ----------------------------------------------------------------------
// return '2';
Expand All @@ -56,9 +62,12 @@
// | ```
// |
// |
// | *@example* — x y
// | *@example*
// | ```tsx
// | x y
// | 12345
// | b
// | ```
// |
// | ----------------------------------------------------------------------
// return '2';
Expand All @@ -80,9 +89,12 @@
// |
// | *@func*
// |
// | *@example* — x y
// | *@example*
// | ```tsx
// | x y
// | 12345
// | b
// | ```
// |
// | ----------------------------------------------------------------------
// return '2';
Expand All @@ -103,9 +115,12 @@
// |
// | *@func*
// |
// | *@example* — x y
// | *@example*
// | ```tsx
// | x y
// | 12345
// | b
// | ```
// |
// | ----------------------------------------------------------------------
// return '2';
Expand All @@ -124,7 +139,7 @@
"item": {
"contents": {
"kind": "markdown",
"value": "```tsx\nfunction foo(): string\n```\n\n\n*@example* — if (true) {\n foo()\n}\n"
"value": "```tsx\nfunction foo(): string\n```\n\n\n*@example*\n```tsx\nif (true) {\n foo()\n}\n```\n"
},
"range": {
"start": {
Expand All @@ -151,7 +166,7 @@
"item": {
"contents": {
"kind": "markdown",
"value": "```tsx\nfunction foo2(): string\n```\n\n\n*@example* — {\n foo()\n}\n"
"value": "```tsx\nfunction foo2(): string\n```\n\n\n*@example*\n```tsx\n{\n foo()\n}\n```\n"
},
"range": {
"start": {
Expand All @@ -178,7 +193,7 @@
"item": {
"contents": {
"kind": "markdown",
"value": "```tsx\nfunction moo(): string\n```\n\n\n*@example* — x y\n 12345\n b\n"
"value": "```tsx\nfunction moo(): string\n```\n\n\n*@example*\n```tsx\n x y\n 12345\n b\n```\n"
},
"range": {
"start": {
Expand All @@ -205,7 +220,7 @@
"item": {
"contents": {
"kind": "markdown",
"value": "```tsx\nfunction boo(): string\n```\n\n\n*@func*\n\n*@example* — x y\n 12345\n b\n"
"value": "```tsx\nfunction boo(): string\n```\n\n\n*@func*\n\n*@example*\n```tsx\n x y\n 12345\n b\n```\n"
},
"range": {
"start": {
Expand All @@ -232,7 +247,7 @@
"item": {
"contents": {
"kind": "markdown",
"value": "```tsx\nfunction goo(): string\n```\n\n\n*@func*\n\n*@example* — x y\n12345\n b\n"
"value": "```tsx\nfunction goo(): string\n```\n\n\n*@func*\n\n*@example*\n```tsx\nx y\n12345\n b\n```\n"
},
"range": {
"start": {
Expand Down