prometeu-studio/discussion/lessons/DSC-0036-pbs-symbol-documentation-and-hover-markdown/LSN-0057-compiler-owned-pbs-doc-markdown-for-editor-assistance.md

---
id: LSN-0057
ticket: pbs-symbol-documentation-and-hover-markdown
title: Compiler-Owned PBS Doc Markdown for Editor Assistance
created: 2026-07-15
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---

## Original Problem

PBS editor assistance had compiler-backed completion, hover, and signature-help surfaces, but it did not yet have a canonical authored documentation model for named API symbols.

Without that model, hover could show mechanical facts such as kind, signature, origin, and type shape, but it could not reliably explain intent, parameter meaning, semantic constraints, or usage notes. Any editor-side solution would have risked reparsing PBS source or inventing a second documentation binding model outside the compiler.

## Consolidated Decision

PBS symbol documentation is authored with a reserved compiler-recognized `Doc` attribute:

```pbs
[Doc(markdown = """
Draws a sprite.

- `x`: screen x coordinate
- `y`: screen y coordinate
""")]
```

The v1 shape is intentionally narrow:

1. `Doc` has exactly one required named argument, `markdown`.
2. The `markdown` argument uses a triple-quoted documentation text block.
3. The text block is documentation-only metadata, not a general runtime multiline string literal.
4. `[Doc]` attaches to the following declaration using the normal PBS attribute association rule.
5. Attribute order is semantically irrelevant.
6. Parameters do not receive `[Doc]` in v1; parameter notes live inside the owning declaration's Markdown.
7. Duplicate `Doc`, missing `markdown`, extra arguments, aliases, positional arguments, empty normalized payloads, and invalid targets are semantic errors.

The compiler owns documentation resolution. LSP and editor consumers receive normalized compiler metadata; they must not reparse PBS source to discover documentation.

## Final Implementation Shape

The work landed as a staged compiler-to-editor pipeline:

1. PBS specs define the syntax, static semantics, AST shape, diagnostics, and stdlib documentation policy for `[Doc(markdown = """...""")]`.
2. The PBS lexer recognizes triple-quoted documentation text blocks without changing ordinary string literal behavior.
3. The parser and AST preserve documentation text block payloads and spans as structured attribute values.
4. A shared normalizer removes incidental surrounding blank lines and common indentation while preserving Markdown content and internal line breaks.
5. Semantic validation reserves `Doc` and enforces the single canonical v1 shape.
6. Normalized Markdown is attached to resolved PBS semantic symbols as structured documentation metadata.
7. PBS editorial and LSP surfaces transport that metadata without source reparsing.
8. Hover composition includes the normalized Markdown while preserving existing fallback behavior for undocumented symbols.
9. Stdlib, SDK, and interface declarations use the same authored documentation surface.
10. Runtime-facing artifacts remain unchanged by documentation metadata.

This preserves a clean boundary: PBS source authors write documentation in the language, the compiler resolves it, LSP transports it, and editors render it.

## Examples

Valid documentation belongs on named API declarations that introduce semantic symbols and can carry attributes, such as functions, methods, services, hosts, interface declarations, and repository-owned stdlib or SDK declarations.

Parameter documentation is written inside the callable's Markdown:

```pbs
[Doc(markdown = """
Fills a rectangle.

- `x`: left edge in screen coordinates
- `y`: top edge in screen coordinates
- `width`: rectangle width in pixels
- `height`: rectangle height in pixels
""")]
```

Invalid v1 forms include:

```pbs
[Doc("Draws a sprite.")]
[Doc(text = """Draws a sprite.""")]
[Doc(markdown = """Draws a sprite.""", format = "markdown")]
[Documentation(markdown = """Draws a sprite.""")]
```

These are rejected because accepting aliases or positional shortcuts would immediately expand the language contract and make future compatibility harder.

## Pitfalls

Do not treat `"""..."""` as a general PBS runtime string literal. Runtime multiline strings raise separate questions about type behavior, lowering, constant pools, equality, escaping, and artifact representation.

Do not let LSP or editor code rediscover documentation by scanning source. That duplicates language semantics outside the compiler and breaks as soon as imports, stdlib declarations, interface modules, or generated sources participate.

Do not attach `[Doc]` to parameters in v1. Parameter docs are authored inside the declaration Markdown so the compiler can keep one documentation payload per API symbol.

Do not reflow authored Markdown in a formatter or hover composer. The normalizer may remove incidental indentation, but it must preserve the author's Markdown content.

Do not lower documentation into runtime artifacts by default. Documentation is compile/editor metadata unless a future runtime or packaging decision explicitly changes that boundary.

## References

- `DEC-0039` captured the normative decision for PBS `Doc` markdown text blocks.
- `PLN-0092` specified the PBS docs and diagnostics contract.
- `PLN-0093` through `PLN-0099` implemented lexer, parser, normalization, semantics, symbol metadata, LSP exposure, and hover composition.
- `PLN-0100` authored stdlib, SDK, and interface documentation.
- `PLN-0101` protected runtime artifacts from documentation lowering.
- `PLN-0102` closed end-to-end conformance coverage.