Repository navigation
Closed
Labels
area/specs.t27 spec files and conformance.t27 spec files and conformanceenhancementNew feature or requestNew feature or requestspec
Description
Doc comments as a first-class thing: parse /// into sections, link [names] to symbols, render them in hover, and give the code blocks inside them the full language service. Mojo does the last one (diagnostics, hover and completion inside docstring code blocks); no HDL server does. Part of the LSP epic, Refs #12209 (wave 2, beyond the standard). Only .t27: no code in any other language, not even scratch probes or a loader; see skill only-t27.
Depends on specs/lsp/hover.t27 (rendering), specs/lsp/navigation.t27 (links) and specs/lsp/analysis.t27 (analysing a code block as a snippet). t27c doc is the reference for what documentation exists.
Prior art:
- Mojo: language server features inside docstring code blocks: https://github.com/modular/vscode-mojo
- rust-analyzer: intra-doc links resolved on hover and go-to-definition, and doc tests as runnables: https://rust-analyzer.github.io/book/features.html
- HLS: haddock rendering in hover: https://haskell-language-server.readthedocs.io/en/latest/features.html
Boundary
- specs/lsp/docs.t27
User Scenarios
- Given a
///block with a summary line, aParamssection, aReturnssection and anExamplecode fence, when it is parsed, then the result holds the 4 parts, and hover shows them as markdown in that order. - Given
[golden_float_mul]in a doc comment, when the user sendstextDocument/definitionon it, then the answer is the function; an unresolved link produces a diagnosticunresolved doc linkwith the nearest name. - Given a code fence in a doc comment with an error in it, when diagnostics run, then the error appears at the right line and column inside the comment.
- Given the cursor inside a code fence, when the client asks for hover or completion, then the answer is computed as if the fence were a snippet of the module, with positions mapped back to the comment.
- Given a public item without a doc comment, when the rule
missing-docsis on, then a hint appears on its name.
Requirements
- FR-001: The module MUST parse doc comments into summary, description, named sections (
Params,Returns,Errors,Example,See also) and code fences, and MUST preserve unknown sections. - FR-002: The module MUST resolve
[name]and[module::name]links through the workspace index and expose them to definition, hover and rename (a rename MUST also rewrite doc links). - FR-003: Code fences tagged
t27or untagged MUST be analysed as a snippet in the scope of the item, with a position map to the comment; a test covers the map in both directions. - FR-004: The module MUST provide the
missing-docsrule data forspecs/lsp/lint.t27, off by default. - FR-005: The parser MUST be total: any comment text yields a result, never an error.
Success Criteria
- At least 25 tests in
specs/lsp/docs.t27pass, run on the lab witht27c test-report(exit 0), including the fence diagnostics and the link rename. - On the lab the parser runs over every
///block inspecs/lsp/without a failure; the block count is pasted in the issue. git diff --name-only masterlists onlyspecs/lsp/docs.t27(0 files in other languages).
Metadata
Metadata
Assignees
Labels
area/specs.t27 spec files and conformance.t27 spec files and conformanceenhancementNew feature or requestNew feature or requestspec
Activity
gHashTag commentedon Nov 17, 2026
LSP spec created (typecheck OK, tests pass).