---
id: PLN-0092
ticket: pbs-symbol-documentation-and-hover-markdown
title: Specify PBS Doc attribute and markdown text block syntax
status: done
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [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`