Properly format @example in quick info
#2329
Conversation
There was a problem hiding this comment.
Pull request overview
This PR improves the formatting of JSDoc @example tags in quick info/hover tooltips by wrapping the example code in proper markdown code blocks instead of displaying it as inline text.
Key Changes
@exampletags now display their content in syntax-highlighted code blocks (using tsx by default) rather than inline text- User-provided code fences in
@exampletags are preserved when detected - New
getCommentTexthelper function extracts plain text from JSDoc comment nodes
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| internal/ls/hover.go | Added special handling for @example tags to format content as code blocks, and introduced getCommentText helper function |
| testdata/baselines/reference/fourslash/quickInfo/quickInfoForJSDocUnknownTag.baseline | Updated test baselines showing improved formatting with code blocks for examples |
| testdata/baselines/reference/fourslash/quickInfo/quickInfoForJSDocCodefence.baseline | Updated test baseline demonstrating preservation of user-provided code fences |
internal/ls/hover.go
Outdated
| 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, "```") { |
There was a problem hiding this comment.
The condition for detecting pre-existing code fences is too permissive and may incorrectly match invalid markdown. The check len(commentText) >= 6 && strings.HasPrefix(commentText, "```") && strings.HasSuffix(commentText, "```") would match strings like "``````" (six consecutive backticks without newlines), which is not a valid markdown code fence. A valid code fence must have content separated by newlines. Consider adding a check for newlines, such as: len(commentText) > 6 && strings.HasPrefix(commentText, "```") && strings.HasSuffix(commentText, "```") && strings.Contains(commentText, "\n") to ensure the matched string is actually a valid multi-line code fence.
| if len(commentText) >= 6 && strings.HasPrefix(commentText, "```") && strings.HasSuffix(commentText, "```") { | |
| if len(commentText) >= 6 && strings.HasPrefix(commentText, "```") && strings.HasSuffix(commentText, "```") && strings.Contains(commentText, "\n") { |
There was a problem hiding this comment.
Reasonable suggestion. Will fix.
| // | | ||
| // | *@example* — `` | ||
| // | *@example* | ||
| // | ```tsx |
There was a problem hiding this comment.
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';
// }
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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.
Fixes #2313.