---
id: PLN-0097
ticket: pbs-symbol-documentation-and-hover-markdown
title: Attach Doc metadata to PBS semantic symbols
status: done
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [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