60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
---
|
|
id: PLN-0094
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Extend PBS attribute parser and AST for Doc markdown payloads
|
|
status: done
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Extend parsing and AST representation so `[Doc(markdown = """...""")]` can be represented structurally before semantic validation.
|
|
|
|
## Objective
|
|
|
|
Parse documentation text block attribute values and expose them in AST without accepting alternate `Doc` shapes as valid semantics.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0092`.
|
|
- Depends on `PLN-0093` for lexer support.
|
|
|
|
## Scope
|
|
|
|
- Extend attribute values to carry documentation text block payloads.
|
|
- Preserve raw payload and spans needed for normalization and diagnostics.
|
|
- Keep parser recovery consistent with existing attribute parsing.
|
|
|
|
## Non-Goals
|
|
|
|
- Validate whether `Doc` is allowed on a declaration.
|
|
- Normalize the text block.
|
|
- Attach documentation to semantic symbols.
|
|
|
|
## Execution Method
|
|
|
|
1. Update `PbsAst.AttributeValue` variants in `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java` to include a documentation text block value or equivalent typed payload.
|
|
2. Update `PbsAttributeParser` so attribute arguments can parse `markdown = """..."""`.
|
|
3. Keep existing string, int, and bool attribute argument parsing unchanged.
|
|
4. Ensure parser diagnostics remain syntax-level: malformed attribute structure is parse error; invalid `Doc` shape is left to semantic validation where possible.
|
|
5. Add parser tests proving `Doc` attributes parse on top-level and nested declaration forms that already support attributes.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `[Doc(markdown = """...""")]` parses into a distinct AST value or unambiguous attribute value representation.
|
|
- Existing attributes such as `[Init]`, `[Frame]`, `[Host(...)]`, and `[InitAllowed]` continue to parse.
|
|
- Invalid generic attribute syntax still recovers at the same boundaries as before.
|
|
|
|
## Tests
|
|
|
|
- Targeted parser tests under `prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser`.
|
|
- Existing PBS parser test suite.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/ast/PbsAst.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/parser/PbsAttributeParser.java`
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/parser/PbsParserTest.java`
|