implements PLN-0092
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user