---
id: PLN-0093
ticket: pbs-symbol-documentation-and-hover-markdown
title: Implement PBS lexer support for documentation text blocks
status: open
created: 2026-07-15
ref_decisions: [DEC-0039]
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
---

## Briefing

Add lexical support for triple-quoted documentation text blocks required by `[Doc(markdown = """...""")]`.

## Objective

Teach the PBS lexer to tokenize documentation text blocks without turning triple quotes into a general runtime string feature.

## Dependencies

- Depends on `PLN-0092` for the normative syntax.

## Scope

- Add a dedicated token kind for documentation text block payloads or an equivalent lexer representation.
- Recognize `"""` open and close delimiters.
- Preserve source text and spans for parser and diagnostics.
- Report unterminated documentation text blocks with useful span information.

## Non-Goals

- Parse or validate `[Doc]` attribute shapes.
- Normalize indentation.
- Lower documentation to runtime artifacts.
- Add general multiline string expressions.

## Execution Method

1. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java` with a documentation text block token if a distinct token is the cleanest local pattern.
2. Update `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java` to recognize `"""..."""` and preserve its raw lexeme and span.
3. Ensure ordinary string scanning remains unchanged for `"..."`.
4. Add or update lexer diagnostics in `LexErrors.java` only if existing unterminated-string diagnostics cannot accurately represent unterminated documentation text blocks.
5. Add focused tests in `PbsLexerTest` for valid text blocks, multiline payloads, embedded single quotes/double quotes, and unterminated blocks.

## Acceptance Criteria

- The lexer can tokenize a multiline documentation text block.
- Unterminated documentation text blocks produce a deterministic diagnostic.
- Ordinary string literals keep current behavior.
- `"""..."""` is not accepted as an expression-level runtime string by this plan.

## Tests

- `./gradlew :prometeu-compiler:frontends:prometeu-frontend-pbs:test` or the repository-equivalent targeted compiler frontend test task.
- Focused `PbsLexerTest` cases for documentation text blocks.

## Affected Artifacts

- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsLexer.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/PbsTokenKind.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/lexer/LexErrors.java`
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/test/java/p/studio/compiler/pbs/lexer/PbsLexerTest.java`