61 lines
2.0 KiB
Markdown
61 lines
2.0 KiB
Markdown
---
|
|
id: PLN-0099
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Render Doc markdown in hover composition
|
|
status: open
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Use transported documentation metadata in hover output while preserving the compiler/LSP/editor ownership boundary.
|
|
|
|
## Objective
|
|
|
|
Compose hover Markdown from signature/kind metadata and normalized `[Doc]` documentation.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0098`.
|
|
|
|
## Scope
|
|
|
|
- Add documentation content to PBS hover composition.
|
|
- Keep Markdown rendering responsibility in the editor/client.
|
|
- Preserve hover behavior for undocumented symbols.
|
|
|
|
## Non-Goals
|
|
|
|
- Automate VSCode visual tests.
|
|
- Define a full documentation website generator.
|
|
- Change signature help parameter documentation behavior.
|
|
|
|
## Execution Method
|
|
|
|
1. Locate the PBS hover composition path in `PbsEditorialSupportService` and LSP bridge/mapping code.
|
|
2. Compose hover Markdown in deterministic order: signature/kind surface, documentation Markdown, then origin/type/shape metadata as currently appropriate.
|
|
3. Avoid escaping or reflowing normalized Markdown beyond safe composition separators.
|
|
4. Ensure undocumented symbols keep existing hover output.
|
|
5. Add hover tests with paragraphs, lists, and code spans from `[Doc]`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Hover includes normalized authored Markdown for documented symbols.
|
|
- Hover does not include empty documentation sections.
|
|
- Markdown lists do not become accidental code blocks due to indentation.
|
|
- VSCode validation remains manual for this wave.
|
|
|
|
## Tests
|
|
|
|
- PBS editorial hover tests.
|
|
- LSP hover mapping tests that assert `MarkupKind.MARKDOWN` payloads.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `PbsEditorialSupportService`
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/compiler`
|
|
- `prometeu-lsp/prometeu-lsp-v1/src/main/java/p/studio/lsp/services/protocol/mapping`
|
|
- Hover-related tests
|