Skip to content

Commit a700617

Browse files
authored
Add introduction sections to JS API and Web API documents (WebAssembly#1814)
These sections provide a bit more background about their relationship to the layer beneath them. They also solve the problem that the existing minimal introductory text was hidden in the bottom of the "status of this document" section.
1 parent 15eb918 commit a700617

File tree

2 files changed

+22
-9
lines changed

2 files changed

+22
-9
lines changed

document/js-api/index.bs

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ Date: now
2323
"title": "WebAssembly Core Specification",
2424
"publisher": "W3C WebAssembly Community Group",
2525
"status": "Draft"
26+
},
27+
"WASMWEB": {
28+
"href": "https://webassembly.github.io/spec/js-api/",
29+
"title": "WebAssembly Web API Specification",
30+
"publisher": "W3C WebAssembly Community Group",
31+
"status": "Draft"
2632
}
2733
}
2834
</pre>
@@ -48,6 +54,8 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
4854
text: ℤ; url: #ℤ
4955
text: SameValue; url: sec-samevalue
5056
urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: dfn
57+
text: embedding interface; url: appending/embedding.html
58+
text: scope; url: intro/introduction.html#scope
5159
url: valid/modules.html#valid-module
5260
text: valid
5361
text: WebAssembly module validation
@@ -174,7 +182,14 @@ emu-const {
174182
}
175183
</style>
176184

177-
This API provides a way to access WebAssembly [[WEBASSEMBLY]] through a bridge to explicitly construct modules from JavaScript [[ECMASCRIPT]].
185+
<h2 id="intro">Introduction</h2>
186+
187+
By design, the [=scope=] of the WebAssembly core specification [[WEBASSEMBLY]] does not include a description of how WebAssembly programs interact with their surrounding execution environment.
188+
Instead it defines an abstract [=embedding interface=] between WebAssembly and its environment, (called the *embedder*).
189+
It is only through this interface that an embedder interacts with the semantics of WebAssembly, and the embedder implements the connection between its host environment and the embedding API.
190+
This document describes the embedding of WebAssembly into JavaScript [[ECMASCRIPT]] environments, including how WebAssembly modules can be constructed and instantiated, how imported and exported functions are called, how data is exchanged, and how errors are handled.
191+
When the JavaScript environment is itself embedded in a Web browser, the Web API spec [[WASMWEB]] describes additional behavior relevant to the Web environment.
192+
178193

179194
<h2 id="sample">Sample API Usage</h2>
180195

document/web-api/index.bs

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,6 @@ Date: now
1818

1919
<pre class='biblio'>
2020
{
21-
"ECMA-262": {
22-
"href": "https://tc39.github.io/ecma262",
23-
"title": "ECMAScript® Language Specification",
24-
"publisher": "ECMA TC39",
25-
"status": "Current Editor's Draft"
26-
},
2721
"WEBASSEMBLY": {
2822
"href": "https://webassembly.github.io/spec/core/",
2923
"title": "WebAssembly Core Specification",
@@ -40,7 +34,7 @@ Date: now
4034
</pre>
4135

4236
<pre class="anchors">
43-
urlPrefix: https://tc39.github.io/ecma262/; spec: ECMA-262
37+
urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
4438
type: exception; for: ECMAScript
4539
text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
4640
type: interface
@@ -71,12 +65,16 @@ url:https://fetch.spec.whatwg.org/#concept-body-consume-body;text:consume body;t
7165
</pre>
7266

7367
<pre class='link-defaults'>
74-
spec:ecma-262; type:exception; for:ECMAScript; text:TypeError
68+
spec:ecmascript; type:exception; for:ECMAScript; text:TypeError
7569
spec:fetch; type:dfn; text:get
7670
spec:webidl; type:dfn; text:resolve
7771
</pre>
7872

73+
74+
<h2 id="intro">Introduction</h2>
7975
This document builds off of the WebAssembly specification [[WEBASSEMBLY]] and the WebAssembly JavaScript embedding [[WASMJS]].
76+
It describes the integration of WebAssembly into the broader Web platform, for example with
77+
additional APIs that are implemented by Web user agents but are outside the scope of JavaScript [[ECMASCRIPT]] itself.
8078

8179
<h2 id="streaming-modules">Streaming Module Compilation and Instantiation</h2>
8280

0 commit comments

Comments
 (0)