---
id: PLN-0096
ticket: pbs-symbol-documentation-and-hover-markdown
title: Validate Doc attribute semantics and diagnostics
status: done
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---

## Briefing

Enforce the semantic contract of `[Doc]` after syntax can represent it.

## Objective

Reject invalid `Doc` usage and produce clear diagnostics for all invalid shapes and targets required by `DEC-0039`.

## Dependencies

- Depends on `PLN-0092`.
- Depends on `PLN-0094`.
- Depends on `PLN-0095`.

## Scope

- Reserve `Doc` as a compiler-recognized attribute.
- Accept only `Doc(markdown = """...""")`.
- Reject aliases, positional arguments, extra arguments, duplicate `Doc`, empty normalized payload, parameter targets, and non-documentable targets.
- Keep duplicates as semantic errors rather than parse errors.

## Non-Goals

- Attach documentation to final symbol metadata.
- Expose documentation through LSP.
- Author stdlib documentation.

## Execution Method

1. Locate existing declaration and reserved attribute validators, including `PbsDeclarationSemanticsValidator`, `PbsDeclarationRuleValidator`, and interface-module reserved attribute checks.
2. Add `Doc` validation in the semantic phase that already validates declaration attributes.
3. Define allowed declaration categories according to the spec: named API declarations that can carry attributes.
4. Add or extend `PbsSemanticsErrors` diagnostics for invalid `Doc` target, invalid shape, duplicate attribute, missing `markdown`, extra arguments, and empty payload.
5. Add tests covering valid declaration targets and every invalid case.

## Acceptance Criteria

- Every invalid shape named by `DEC-0039` produces a semantic diagnostic.
- Parameters never accept `[Doc]`.
- Duplicate `[Doc]` on one declaration is rejected semantically.
- Existing reserved attributes keep their current behavior.

## Tests

- `PbsSemanticsDeclarationsTest`
- `PbsInterfaceModuleSemanticsTest`
- `PbsDiagnosticsContractTest`

## Affected Artifacts

- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationSemanticsValidator.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsDeclarationRuleValidator.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/semantics/PbsSemanticsErrors.java`
- PBS semantics tests