implements PLN-0092

This commit is contained in:
2026-07-15 06:55:26 +01:00
parent ad2ae00f39
commit 917b0e1b9a
19 changed files with 955 additions and 18 deletions
@@ -80,7 +80,7 @@ Rules:
- Attributes are not first-class values and are not reflectable in v1 core.
- Attributes do not automatically survive into runtime or bytecode artifacts.
- An attribute affects runtime artifacts only when another specification defines an explicit lowering for its semantic effect.
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `AssetLowering`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, and `InitAllowed`.
- In v1 core, the normative reserved attributes are `Host`, `Capability`, `AssetLowering`, `BuiltinType`, `BuiltinConst`, `IntrinsicCall`, `Init`, `Frame`, `InitAllowed`, and `Doc`.
- `Host` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
- `Capability` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
- `AssetLowering` is valid only on a host method signature declared directly inside a reserved stdlib/interface-module `declare host` body.
@@ -100,6 +100,42 @@ Rules:
- Builtin metadata is consumed by the compiler during VM-owned builtin and intrinsic lowering rather than by host-binding lowering.
- `Init` and `Frame` are consumed by lifecycle analysis and lowering rather than by ordinary runtime reflection.
- `InitAllowed` is consumed by init-time host-admission analysis and does not become ordinary userland metadata.
- `Doc` is compile/editor documentation metadata and is consumed by compiler-owned editorial surfaces.
- `Doc` MUST NOT be lowered into bytecode, PBX, cartridge, or runtime-facing artifacts unless a future specification explicitly defines such lowering.
### 2.3.1 `Doc` documentation metadata
`Doc` attaches authored Markdown documentation to a named API declaration.
Canonical v1 shape:
```pbs
[Doc(markdown = """
Draws a sprite.
- `x`: screen x
- `y`: screen y
""")]
```
Rules:
- `Doc` MUST declare exactly one named argument, `markdown`.
- `Doc.markdown` MUST be a documentation text block.
- `Doc` MUST NOT accept aliases or alternate forms such as `text`, positional arguments, `html`, `format`, `Document`, `Documentation`, or `md"""..."""`.
- A declaration MUST NOT carry more than one `Doc` attribute.
- Duplicate `Doc` attributes are static semantic errors and must not be rejected only as parser errors.
- Attribute order is semantically irrelevant; `Doc` colocated with other valid attributes has the same meaning regardless of ordering.
- `Doc` is valid only on named API declarations that introduce named semantic symbols and can carry attributes.
- The v1 documentable surface includes functions, methods, classes/structs when present, services, hosts, builtin and stdlib declarations, and interface declarations.
- Parameters MUST NOT receive `Doc` in v1. Parameter documentation, when present, MUST be authored inside the Markdown payload of the owning declaration.
- Fields, enum cases, tuple fields, local variables, expressions, and other non-API declaration surfaces MUST NOT receive `Doc` unless a future decision explicitly classifies them as documentable named API declarations.
- Documentation text block content MUST be normalized before semantic empty-payload validation and before exposure to editor consumers.
- Normalization MUST remove an incidental leading empty line, remove an incidental trailing empty line, compute the common indentation of non-empty content lines, remove that common indentation, preserve internal line breaks, and preserve Markdown content after indentation normalization.
- A normalized empty or whitespace-only `Doc.markdown` payload is invalid.
- The authored format is a supported Markdown subset. Rendering, sanitization, and unsupported Markdown constructs are consumer responsibilities.
- Compiler semantic metadata MUST preserve normalized Markdown documentation as metadata of the documented symbol.
- LSP and editor consumers MUST consume compiler-resolved documentation metadata rather than reparsing source text.
### 2.4 Tuple shapes