prometeu-studio/discussion/workflow/plans/PLN-0097-attach-doc-metadata-to-pbs-semantic-symbols.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0097	pbs-symbol-documentation-and-hover-markdown	Attach Doc metadata to PBS semantic symbols	open	2026-07-15	DEC-0039	compiler compiler-pbs studio lsp vscode editor hover documentation markdown

Briefing

Once [Doc] is syntactically and semantically valid, attach normalized documentation to compiler-owned semantic symbol data.

Objective

Make documentation available from resolved PBS symbols without requiring LSP or editor code to reparse source.

Dependencies

• Depends on PLN-0095.
• Depends on PLN-0096.

Scope

• Introduce an internal documentation metadata model with format and text.
• Attach normalized Markdown to documented named API symbols.
• Preserve the distinction between documentation metadata and runtime semantics.

Non-Goals

• Render hover markdown.
• Write stdlib documentation content.
• Lower documentation into runtime artifacts.

Execution Method

1. Add a compiler-side documentation metadata model, for example format = markdown plus normalized text.
2. Extend symbol or editorial-resolution structures so documented declarations expose this metadata.
3. Update symbol collection/binding paths for functions, methods, structs/classes, services, hosts, builtin/stdlib declarations, and interface declarations.
4. Ensure imported/stdlib declarations can carry the same metadata once parsed.
5. Add compiler tests proving documentation is attached to the intended declaration and not to parameters or unrelated symbols.

Acceptance Criteria

• Resolved symbols can expose documentation as structured metadata, not an untyped hover-only string.
• Documentation metadata is absent for undocumented symbols.
• Documentation does not change type checking, name resolution, or runtime behavior.

Tests

• Focused PBS semantic/editorial support tests.
• Existing name resolution and declaration tests to catch regressions.

Affected Artifacts

• prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics
• PbsEditorialResolvedSymbol
• PbsEditorialSupportService
• Symbol/declaration binding code touched by documented declaration categories