---
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`