prometeu-studio/discussion/workflow/plans/PLN-0093-implement-pbs-lexer-support-for-documentation-text-blocks.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0093	pbs-symbol-documentation-and-hover-markdown	Implement PBS lexer support for documentation text blocks	done	2026-07-15	DEC-0039	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