Skip to content

Commit

Permalink
Add introduction sections to JS API and Web API documents (#1814)
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
dschuff authored Sep 30, 2024
1 parent 15eb918 commit a700617
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 9 deletions.
17 changes: 16 additions & 1 deletion document/js-api/index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,12 @@ Date: now
"title": "WebAssembly Core Specification",
"publisher": "W3C WebAssembly Community Group",
"status": "Draft"
},
"WASMWEB": {
"href": "https://webassembly.github.io/spec/js-api/",
"title": "WebAssembly Web API Specification",
"publisher": "W3C WebAssembly Community Group",
"status": "Draft"
}
}
</pre>
Expand All @@ -48,6 +54,8 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
text: ℤ; url: #ℤ
text: SameValue; url: sec-samevalue
urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: dfn
text: embedding interface; url: appending/embedding.html
text: scope; url: intro/introduction.html#scope
url: valid/modules.html#valid-module
text: valid
text: WebAssembly module validation
Expand Down Expand Up @@ -174,7 +182,14 @@ emu-const {
}
</style>

This API provides a way to access WebAssembly [[WEBASSEMBLY]] through a bridge to explicitly construct modules from JavaScript [[ECMASCRIPT]].
<h2 id="intro">Introduction</h2>

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.
Instead it defines an abstract [=embedding interface=] between WebAssembly and its environment, (called the *embedder*).
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.
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.
When the JavaScript environment is itself embedded in a Web browser, the Web API spec [[WASMWEB]] describes additional behavior relevant to the Web environment.


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

Expand Down
14 changes: 6 additions & 8 deletions document/web-api/index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -18,12 +18,6 @@ Date: now

<pre class='biblio'>
{
"ECMA-262": {
"href": "https://tc39.github.io/ecma262",
"title": "ECMAScript® Language Specification",
"publisher": "ECMA TC39",
"status": "Current Editor's Draft"
},
"WEBASSEMBLY": {
"href": "https://webassembly.github.io/spec/core/",
"title": "WebAssembly Core Specification",
Expand All @@ -40,7 +34,7 @@ Date: now
</pre>

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

<pre class='link-defaults'>
spec:ecma-262; type:exception; for:ECMAScript; text:TypeError
spec:ecmascript; type:exception; for:ECMAScript; text:TypeError
spec:fetch; type:dfn; text:get
spec:webidl; type:dfn; text:resolve
</pre>


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

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

Expand Down

0 comments on commit a700617

Please sign in to comment.