prometeu-studio/discussion/workflow/plans/PLN-0099-render-doc-markdown-in-hover-composition.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0099	pbs-symbol-documentation-and-hover-markdown	Render Doc markdown in hover composition	done	2026-07-15	DEC-0039	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