prometeu-studio/discussion/workflow/plans/PLN-0092-specify-pbs-doc-attribute-and-markdown-text-block-syntax.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0092	pbs-symbol-documentation-and-hover-markdown	Specify PBS Doc attribute and markdown text block syntax	done	2026-07-15	DEC-0039	compiler compiler-pbs studio lsp vscode editor hover documentation markdown

Briefing

Update the PBS normative specs so DEC-0039 is reflected before code changes begin. This plan is the specification gate for the [Doc(markdown = """...""")] feature.

Objective

Define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for compiler-owned PBS symbol documentation.

Dependencies

• Requires accepted decision DEC-0039.
• Must be completed before parser, semantic, LSP, and stdlib implementation plans are accepted as complete.

Scope

• Add [Doc(markdown = """...""")] to the PBS attribute surface.
• Define triple-quoted documentation text blocks as documentation-only payloads, not runtime strings.
• Define documentable named API declarations and explicitly exclude parameters.
• Define normalization, duplicate handling, invalid shape diagnostics, and non-runtime lowering rules.

Non-Goals

• Implement lexer, parser, semantics, or LSP code.
• Define general multiline runtime strings.
• Define VSCode rendering details beyond the compiler/LSP ownership boundary.

Execution Method

1. Update docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md with the canonical [Doc(markdown = """...""")] syntax, allowed declaration sites, attribute ordering rule, and text block delimiter rules.
2. Update docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md with reserved Doc validation, duplicate rejection, parameter exclusion, empty normalized payload rejection, and non-documentable target diagnostics.
3. Update docs/specs/compiler-languages/pbs/11. AST Specification.md with an AST representation for documentation attributes and documentation text block payloads.
4. Update docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md with required diagnostic categories for unterminated text block, invalid Doc shape, duplicate Doc, empty payload, and invalid target.
5. Update docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md with the rule that stdlib, SDK, and interface modules use the same authored Doc surface.

Acceptance Criteria

• Specs define all normative rules from DEC-0039 without deferring syntax or semantics to implementation judgment.
• The specs explicitly state that """...""" is documentation-only for this feature.
• The specs explicitly state that parameters never receive [Doc] in v1.
• The specs identify propagation boundaries: compiler resolves, LSP transports, editor renders.

Tests

• Run any existing spec conformance tests that validate PBS spec references.
• No code behavior tests are required in this plan.

Affected Artifacts

• docs/specs/compiler-languages/pbs/3. Core Syntax Specification.md
• docs/specs/compiler-languages/pbs/4. Static Semantics Specification.md
• docs/specs/compiler-languages/pbs/11. AST Specification.md
• docs/specs/compiler-languages/pbs/12. Diagnostics Specification.md
• docs/specs/compiler-languages/pbs/5. Manifest, Stdlib, and SDK Resolution Specification.md