prometeu-studio/discussion/workflow/plans/PLN-0094-extend-pbs-attribute-parser-and-ast-for-doc-markdown-payloads.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0094	pbs-symbol-documentation-and-hover-markdown	Extend PBS attribute parser and AST for Doc markdown payloads	done	2026-07-15	DEC-0039	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