Support <caption></caption> in JSDoc @example tags
#2374
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds support for parsing <caption></caption> tags within JSDoc @example tags. When a caption is present, it's extracted and displayed as part of the hover documentation, separated by an em-dash, with the caption text appearing before the example code.
Key changes:
- Caption extraction logic that finds and extracts text between
<caption>and</caption>tags - Blank line trimming to clean up whitespace after the caption tags
- Repositioning of the newline output to occur after caption processing
| if strings.HasPrefix(commentText, "<caption>") { | ||
| if captionEnd := strings.Index(commentText, "</caption>"); captionEnd > 0 { | ||
| b.WriteString(" — ") | ||
| b.WriteString(commentText[len("<caption>"):captionEnd]) | ||
| commentText = commentText[captionEnd+len("</caption>"):] | ||
| // Trim leading blank lines from commentText | ||
| for { | ||
| s1 := strings.TrimLeft(commentText, " \t") | ||
| s2 := strings.TrimLeft(s1, "\r\n") | ||
| if len(s1) == len(s2) { | ||
| break | ||
| } | ||
| commentText = s2 | ||
| } | ||
| } | ||
| } |
There was a problem hiding this comment.
This caption extraction feature lacks test coverage. According to the project guidelines, when implementing a new feature, at least one minimal test case should always be added to verify the fix. Please add a test case in testdata/tests/cases/compiler/ that demonstrates JSDoc @example tags with <caption></caption> tags to verify this functionality works correctly.
| b.WriteString("\n") | ||
| commentText := strings.TrimRight(getCommentText(comments), " \t\r\n") | ||
| if strings.HasPrefix(commentText, "<caption>") { | ||
| if captionEnd := strings.Index(commentText, "</caption>"); captionEnd > 0 { |
There was a problem hiding this comment.
The condition captionEnd > 0 allows empty captions (e.g., <caption></caption>) to be processed, which will result in an em-dash followed by nothing. Consider using captionEnd > len("<caption>") to only process captions that contain actual content, or document that empty captions are intentionally supported.
| if captionEnd := strings.Index(commentText, "</caption>"); captionEnd > 0 { | |
| if captionEnd := strings.Index(commentText, "</caption>"); captionEnd > len("<caption>") { |
Fixes #2349.