Skip to content

Commit 842b488

Browse files
authored
Add more documentation about types. (#288)
Add documentation describing the floating-point types, and briefly describe the difference between core-wasm numeric types and component-level numeric types. Add more subsection headings to the prose describing the types, breaking up a sizeable quantity of text, and adding anchors that can be linked to. In particular, I've often wanted an anchor for "handle types". And, fix the number of definition types.
1 parent f3486b2 commit 842b488

File tree

1 file changed

+42
-3
lines changed

1 file changed

+42
-3
lines changed

design/mvp/Explainer.md

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ JavaScript runtimes. For a more user-focussed explanation, take a look at the
1111
* [Instance definitions](#instance-definitions)
1212
* [Alias definitions](#alias-definitions)
1313
* [Type definitions](#type-definitions)
14+
* [Fundamental value types](#fundamental-value-types)
15+
* [Numeric types](#numeric-types)
16+
* [Container types](#container-types)
17+
* [Handle types](#handle-types)
18+
* [Specialized value types](#specialized-value-types)
19+
* [Definition types](#definition-types)
20+
* [Declarators](#declarators)
1421
* [Type checking](#type-checking)
1522
* [Canonical definitions](#canonical-definitions)
1623
* [Canonical ABI](#canonical-built-ins)
@@ -560,6 +567,9 @@ typebound ::= (eq <typeidx>)
560567
561568
where bind-id(X) parses '(' sort <id>? Y ')' when X parses '(' sort Y ')'
562569
```
570+
571+
#### Fundamental value types
572+
563573
The value types in `valtype` can be broken into two categories: *fundamental*
564574
value types and *specialized* value types, where the latter are defined by
565575
expansion into the former. The *fundamental value types* have the following
@@ -569,7 +579,7 @@ sets of abstract values:
569579
| `bool` | `true` and `false` |
570580
| `s8`, `s16`, `s32`, `s64` | integers in the range [-2<sup>N-1</sup>, 2<sup>N-1</sup>-1] |
571581
| `u8`, `u16`, `u32`, `u64` | integers in the range [0, 2<sup>N</sup>-1] |
572-
| `float32`, `float64` | [IEEE754] floating-point numbers |
582+
| `float32`, `float64` | [IEEE754] floating-point numbers, with a single NaN value |
573583
| `char` | [Unicode Scalar Values] |
574584
| `record` | heterogeneous [tuples] of named values |
575585
| `variant` | heterogeneous [tagged unions] of named values |
@@ -584,6 +594,29 @@ For example, while abstract `variant`s contain a list of `case`s labelled by
584594
name, canonical lifting and lowering map each case to an `i32` value starting
585595
at `0`.
586596

597+
##### Numeric types
598+
599+
While core numeric types are defined in terms of sets of bit-patterns and
600+
operations that interpret the bits in various ways, component-level numeric
601+
types are defined in terms of sets of values. This allows the values to be
602+
translated between source languages and protocols that use different
603+
value representations.
604+
605+
Core integer types are just bit-patterns that don't distinguish between signed
606+
and unsigned, while component-level integer types are sets of integers that
607+
either include negative values or don't. Core floating-point types have many
608+
distinct NaN bit-patterns, while component-level floating-point types have only
609+
a single NaN value. And boolean values in core wasm are usually represented as
610+
`i32`s where operations interpret all-zeros as `false`, while at the
611+
component-level there is a `bool` type with `true` and `false` values.
612+
613+
##### Container types
614+
615+
The `record`, `variant`, and `list` types allow for grouping, categorizing,
616+
and sequencing contained values.
617+
618+
##### Handle types
619+
587620
The `own` and `borrow` value types are both *handle types*. Handles logically
588621
contain the opaque address of a resource and avoid copying the resource when
589622
passed across component boundaries. By way of metaphor to operating systems,
@@ -598,6 +631,8 @@ through these canonical definitions. The `typeidx` immediate of a handle type
598631
must refer to a `resource` type (described below) that statically classifies
599632
the particular kinds of resources the handle can point to.
600633

634+
#### Specialized value types
635+
601636
The sets of values allowed for the remaining *specialized value types* are
602637
defined by the following mapping:
603638
```
@@ -613,8 +648,10 @@ cases. This could be relaxed in the future to allow an empty list of cases, with
613648
the empty `(variant)` effectively serving as a [empty type] and indicating
614649
unreachability.
615650

616-
The remaining 3 type constructors in `deftype` use `valtype` to describe
617-
shared-nothing functions, components and component instances:
651+
#### Definition types
652+
653+
The remaining 4 type constructors in `deftype` use `valtype` to describe
654+
shared-nothing functions, resources, components, and component instances:
618655

619656
The `func` type constructor describes a component-level function definition
620657
that takes and returns a list of `valtype`. In contrast to [`core:functype`],
@@ -657,6 +694,8 @@ declarators. The meanings of these declarators is basically the same as the
657694
core module declarators introduced above, but expanded to cover the additional
658695
capabilities of the component model.
659696

697+
#### Declarators
698+
660699
The `importdecl` and `exportdecl` declarators correspond to component `import`
661700
and `export` definitions, respectively, allowing an identifier to be bound for
662701
use by subsequent declarators. The definitions of `label`, `importname` and

0 commit comments

Comments
 (0)