Skip to content

fix: preserve fenced code in hover documentation - #3495

Open
sogav21 wants to merge 2 commits into
LuaLS:masterfrom
sogav21:codex/issue-3435-hover-code-examples
Open

sogav21 wants to merge 2 commits into
LuaLS:masterfrom
sogav21:codex/issue-3435-hover-code-examples

Conversation

@sogav21

@sogav21 sogav21 commented Nov 10, 2026

Copy link
Copy Markdown

Preserve fenced code examples in hover comments so expressions such as t[i](...) are displayed as written. Relative Markdown links in the surrounding prose continue to resolve.

Fixes #3435.

Validation

  • The crossfile hover regression reproduced the rewritten code before the fix and passes for backtick and tilde fences with the fix.
  • The full Windows LuaLS test suite passed. A JSON-RPC hover request also preserved the code and resolved the adjacent prose link.

Developed with AI assistance.

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

中文:在 normalizeComment 中,context 参数被声明为 { fence: string? },但 getBindComment、lookUpDocComments、getFunctionCommentMarkdown 等调用方传入的是 {},这没问题;不过 tryDocFieldComment 每次调用都新建 {},导致跨注释的围栏状态无法延续。如果某个字段注释的 fenced code block 跨越多条 LuaDoc 注释,围栏状态会在每次调用时丢失,从而可能错误地解析代码块内的链接。建议确认这是否是有意为之,或复用同一 context。

English: In normalizeComment, context is typed as { fence: string? }, and callers such as getBindComment, lookUpDocComments, and getFunctionCommentMarkdown pass {}, which is fine; however, tryDocFieldComment creates a new {} on every call, so fenced-code state cannot carry across comments. If a field comment's fenced code block spans multiple LuaDoc comments, the fence state is lost on each call, which may incorrectly resolve links inside code blocks. Please confirm whether this is intentional or reuse a shared context.

中文:围栏闭合判断使用 rest:match('^%s*$'),但 rest 来自 line:match('^ ? ? ?(```+)([^\r\n]*)'),其中 [^\r\n]* 已排除换行,因此 %s* 也会匹配空格和制表符。按 CommonMark,闭合围栏后只允许空白,这一点是正确的;但开启围栏时使用 rest:find('', 1, true)排除反引号,仅对反引号围栏生效,对~~~围栏没有对应限制(CommonMark 中~` 围栏的 info string 可包含反引号)。这看起来是有意区分,但建议补充注释说明,避免后续维护者误改。

English: The closing-fence check uses rest:match('^%s*$'), where rest comes from line:match('^ ? ? ?(```+)([^\r\n]*)'); since [^\r\n]* already excludes newlines, %s* also matches spaces and tabs. Per CommonMark, only whitespace is allowed after a closing fence, so this is correct; however, the opening-fence check uses rest:find('', 1, true)to reject backticks, which only applies to backtick fences and has no equivalent restriction for~~~fences (in CommonMark, a~` fence's info string may contain backticks). This appears intentional, but a comment explaining it would help prevent future maintainers from changing it by mistake.

中文:resolveLinks 中 path 为空字符串时,furi.split('') 的返回值以及 ws.getAbsolutePath 的行为未在本次改动中验证;原逻辑相同,但重构后该分支被包进闭包,建议确认空路径不会产生异常 URI。

English: In resolveLinks, when path is an empty string, the return value of furi.split('') and the behavior of ws.getAbsolutePath are not verified in this change; the original logic was the same, but after the refactor this branch is wrapped in a closure. Please confirm that an empty path does not produce an invalid URI.

中文:测试覆盖了反引号围栏、波浪线围栏以及围栏内链接不被解析的情况,但未覆盖“围栏跨多条 LuaDoc 注释”的场景,而这正是新增 context.fence 的主要目的。建议补充一个跨注释围栏的测试,以验证状态传递正确。

English: The tests cover backtick fences, tilde fences, and links inside fences not being resolved, but they do not cover the case where a fence spans multiple LuaDoc comments, which is the main purpose of the new context.fence. Please add a test for a cross-comment fence to verify that state is passed correctly.

@sogav21

sogav21 commented Nov 10, 2026

Copy link
Copy Markdown
Author

Thanks for the review. Both fence regressions span separate LuaDoc comment nodes. Leading field comments share the context through getBindComment, and the direct field path scans the complete tail-comment text in one call. A base/head hover comparison also produced the same URI for an empty Markdown destination outside a fence.

While checking the fence rules, I found that Lua's %s allowed form feed or vertical tab to end a fence. Updated in 7beb0825d9 to allow spaces and tabs and added a regression for the form-feed case. The full Windows test suite passed. The code now explains the different rules for backtick and tilde info strings.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Hyperlink markdown still evaluated within a code block

1 participant