61 lines
2.2 KiB
Markdown
61 lines
2.2 KiB
Markdown
---
|
|
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
|