Skip to content

LSP: doc comments, doc links and code blocks in docs (specs/lsp/docs.t27) #12259

Closed

Description

@gHashTag

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:

Boundary

  • specs/lsp/docs.t27

User Scenarios

  • Given a /// block with a summary line, a Params section, a Returns section and an Example code 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 sends textDocument/definition on it, then the answer is the function; an unresolved link produces a diagnostic unresolved doc link with 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-docs is 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 t27 or 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-docs rule data for specs/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.t27 pass, run on the lab with t27c test-report (exit 0), including the fence diagnostics and the link rename.
  • On the lab the parser runs over every /// block in specs/lsp/ without a failure; the block count is pasted in the issue.
  • git diff --name-only master lists only specs/lsp/docs.t27 (0 files in other languages).

Activity

  1. gHashTag commented on Nov 17, 2026

    @gHashTag
    CollaboratorAuthor

    LSP spec created (typecheck OK, tests pass).

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/specs.t27 spec files and conformanceenhancementNew feature or requestspec

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions