63 lines
2.8 KiB
Markdown
63 lines
2.8 KiB
Markdown
---
|
|
id: PLN-0093
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Implement PBS lexer support for documentation text blocks
|
|
status: done
|
|
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`
|