61 lines
2.0 KiB
Markdown
61 lines
2.0 KiB
Markdown
---
|
|
id: PLN-0100
|
|
ticket: pbs-symbol-documentation-and-hover-markdown
|
|
title: Author Doc metadata for stdlib SDK and interface declarations
|
|
status: open
|
|
created: 2026-07-15
|
|
ref_decisions: [DEC-0039]
|
|
tags: [compiler, compiler-pbs, studio, lsp, vscode, editor, hover, documentation, markdown]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Apply the new documentation model to repository-owned PBS stdlib, SDK, and interface declarations.
|
|
|
|
## Objective
|
|
|
|
Author English `[Doc(markdown = """...""")]` documentation for stdlib/API surfaces so editor assistance has useful content.
|
|
|
|
## Dependencies
|
|
|
|
- Depends on `PLN-0092`.
|
|
- Should run after `PLN-0096` so authored docs are validated by compiler tests.
|
|
- Benefits from `PLN-0099` for hover verification but does not require it to author source docs.
|
|
|
|
## Scope
|
|
|
|
- Add English Markdown documentation to stdlib, SDK, and interface declarations.
|
|
- Document parameters inside the owning declaration Markdown.
|
|
- Keep documentation concise and API-focused.
|
|
|
|
## Non-Goals
|
|
|
|
- Add `[Doc]` to parameters.
|
|
- Generate external documentation sites.
|
|
- Change stdlib semantics or host binding behavior.
|
|
|
|
## Execution Method
|
|
|
|
1. Inventory stdlib and SDK PBS files under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib`.
|
|
2. Add `[Doc(markdown = """...""")]` to public named API declarations that users see in completion/hover.
|
|
3. Document parameter meaning inside callable Markdown when needed.
|
|
4. Ensure host/interface declarations use the same `Doc` shape.
|
|
5. Run stdlib compile and interface conformance tests.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- Public stdlib/SDK declarations that are user-facing have concise English documentation.
|
|
- No parameters receive `[Doc]`.
|
|
- Existing stdlib behavior and host ABI bindings are unchanged.
|
|
|
|
## Tests
|
|
|
|
- `PbsGateUStdlibCompileTest`
|
|
- `PbsGateUSdkInterfaceConformanceTest`
|
|
- Relevant PBS frontend tests.
|
|
|
|
## Affected Artifacts
|
|
|
|
- `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/game/stdlib/1/**`
|
|
- Stdlib/interface compile tests
|