Merge pull request WebAssembly#90 from sunfishcode/sunfishcode/comments

Convert `//`-style comments to `///`.

.github/workflows/main.yml

@@ -10,12 +10,12 @@ jobs:
     name: Check ABI files are up-to-date
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: ensure `./wit/deps` are in sync
       run: |
         curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.3/wit-deps-x86_64-unknown-linux-musl
         chmod +x wit-deps
         ./wit-deps lock
         git add -N wit/deps
         git diff --exit-code
-    - uses: WebAssembly/wit-abi-up-to-date@v16
+    - uses: WebAssembly/wit-abi-up-to-date@v17

imports.md

@@ -20,6 +20,9 @@
 <hr />
 <h3>Types</h3>
 <h4><a name="network"><code>resource network</code></a></h4>
+<p>An opaque resource that represents access to (a subset of) the network.
+This enables context-based security for networking.
+There is no need for this to map 1:1 to a physical network interface.</p>
 <h4><a name="error_code"><code>enum error-code</code></a></h4>
 <p>Error codes.</p>
 <p>In theory, every API can return any error code.
@@ -102,18 +105,20 @@ combined with a couple of errors that are always possible:</p>
 </li>
 <li>
 <p><a name="error_code.connection_refused"><code>connection-refused</code></a></p>
-<p>The connection was forcefully rejected
+<p>The TCP connection was forcefully rejected
 </li>
 <li>
 <p><a name="error_code.connection_reset"><code>connection-reset</code></a></p>
-<p>The connection was reset.
+<p>The TCP connection was reset.
 </li>
 <li>
 <p><a name="error_code.connection_aborted"><code>connection-aborted</code></a></p>
-<p>A connection was aborted.
+<p>A TCP connection was aborted.
 </li>
 <li>
 <p><a name="error_code.datagram_too_large"><code>datagram-too-large</code></a></p>
+<p>The size of a datagram sent to a UDP socket exceeded the maximum
+supported size.
 </li>
 <li>
 <p><a name="error_code.name_unresolvable"><code>name-unresolvable</code></a></p>
@@ -169,16 +174,34 @@ combined with a couple of errors that are always possible:</p>
 <h4><a name="ipv4_socket_address"><code>record ipv4-socket-address</code></a></h4>
 <h5>Record Fields</h5>
 <ul>
-<li><a name="ipv4_socket_address.port"><code>port</code></a>: <code>u16</code></li>
-<li><a name="ipv4_socket_address.address"><code>address</code></a>: <a href="#ipv4_address"><a href="#ipv4_address"><code>ipv4-address</code></a></a></li>
+<li>
+<p><a name="ipv4_socket_address.port"><code>port</code></a>: <code>u16</code></p>
+<p>sin_port
+</li>
+<li>
+<p><a name="ipv4_socket_address.address"><code>address</code></a>: <a href="#ipv4_address"><a href="#ipv4_address"><code>ipv4-address</code></a></a></p>
+<p>sin_addr
+</li>
 </ul>
 <h4><a name="ipv6_socket_address"><code>record ipv6-socket-address</code></a></h4>
 <h5>Record Fields</h5>
 <ul>
-<li><a name="ipv6_socket_address.port"><code>port</code></a>: <code>u16</code></li>
-<li><a name="ipv6_socket_address.flow_info"><code>flow-info</code></a>: <code>u32</code></li>
-<li><a name="ipv6_socket_address.address"><code>address</code></a>: <a href="#ipv6_address"><a href="#ipv6_address"><code>ipv6-address</code></a></a></li>
-<li><a name="ipv6_socket_address.scope_id"><code>scope-id</code></a>: <code>u32</code></li>
+<li>
+<p><a name="ipv6_socket_address.port"><code>port</code></a>: <code>u16</code></p>
+<p>sin6_port
+</li>
+<li>
+<p><a name="ipv6_socket_address.flow_info"><code>flow-info</code></a>: <code>u32</code></p>
+<p>sin6_flowinfo
+</li>
+<li>
+<p><a name="ipv6_socket_address.address"><code>address</code></a>: <a href="#ipv6_address"><a href="#ipv6_address"><code>ipv6-address</code></a></a></p>
+<p>sin6_addr
+</li>
+<li>
+<p><a name="ipv6_socket_address.scope_id"><code>scope-id</code></a>: <code>u32</code></p>
+<p>sin6_scope_id
+</li>
 </ul>
 <h4><a name="ip_socket_address"><code>variant ip-socket-address</code></a></h4>
 <h5>Variant Cases</h5>
@@ -207,7 +230,7 @@ at once.</p>
 <hr />
 <h3>Types</h3>
 <h4><a name="pollable"><code>resource pollable</code></a></h4>
-<hr />
+<h2><a href="#pollable"><code>pollable</code></a> epresents a single I/O event which may be ready, or not.</h2>
 <h3>Functions</h3>
 <h4><a name="method_pollable.ready"><code>[method]pollable.ready: func</code></a></h4>
 <p>Return the readiness of a pollable. This function never blocks.</p>
@@ -305,6 +328,7 @@ being reaedy for I/O.</p>
 </li>
 </ul>
 <h4><a name="udp_socket"><code>resource udp-socket</code></a></h4>
+<p>A UDP socket handle.</p>
 <h4><a name="incoming_datagram_stream"><code>resource incoming-datagram-stream</code></a></h4>
 <h4><a name="outgoing_datagram_stream"><code>resource outgoing-datagram-stream</code></a></h4>
 <hr />
@@ -740,7 +764,21 @@ the socket is effectively an in-memory configuration object, unable to communica
 <hr />
 <h3>Types</h3>
 <h4><a name="error"><code>resource error</code></a></h4>
-<hr />
+<p>A resource which represents some error information.</p>
+<p>The only method provided by this resource is <code>to-debug-string</code>,
+which provides some human-readable information about the error.</p>
+<p>In the <code>wasi:io</code> package, this resource is returned through the
+<code>wasi:io/streams/stream-error</code> type.</p>
+<p>To provide more specific error information, other interfaces may
+provide functions to further &quot;downcast&quot; this error into more specific
+error information. For example, <a href="#error"><code>error</code></a>s returned in streams derived
+from filesystem types to be described using the filesystem's own
+error-code type, using the function
+<code>wasi:filesystem/types/filesystem-error-code</code>, which takes a parameter
+<code>borrow&lt;error&gt;</code> and returns
+<code>option&lt;wasi:filesystem/types/error-code&gt;</code>.</p>
+<h2>The set of functions which can &quot;downcast&quot; an <a href="#error"><code>error</code></a> into a more
+concrete type is open.</h2>
 <h3>Functions</h3>
 <h4><a name="method_error.to_debug_string"><code>[method]error.to-debug-string: func</code></a></h4>
 <p>Returns a string that is suitable to assist humans in debugging
@@ -787,8 +825,21 @@ future operations.
 </li>
 </ul>
 <h4><a name="input_stream"><code>resource input-stream</code></a></h4>
+<p>An input bytestream.</p>
+<p><a href="#input_stream"><code>input-stream</code></a>s are <em>non-blocking</em> to the extent practical on underlying
+platforms. I/O operations always return promptly; if fewer bytes are
+promptly available than requested, they return the number of bytes promptly
+available, which could even be zero. To wait for data to be available,
+use the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be polled
+for using <code>wasi:io/poll</code>.</p>
 <h4><a name="output_stream"><code>resource output-stream</code></a></h4>
-<hr />
+<p>An output bytestream.</p>
+<h2><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> to the extent practical on
+underlying platforms. Except where specified otherwise, I/O operations also
+always return promptly, after the number of bytes that can be written
+promptly, which could even be zero. To wait for the stream to be ready to
+accept data, the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be
+polled for using <code>wasi:io/poll</code>.</h2>
 <h3>Functions</h3>
 <h4><a name="method_input_stream.read"><code>[method]input-stream.read: func</code></a></h4>
 <p>Perform a non-blocking read from the stream.</p>
@@ -1165,7 +1216,7 @@ occured.</p>
 </li>
 </ul>
 <h4><a name="tcp_socket"><code>resource tcp-socket</code></a></h4>
-<hr />
+<h2>A TCP socket handle.</h2>
 <h3>Functions</h3>
 <h4><a name="method_tcp_socket.start_bind"><code>[method]tcp-socket.start-bind: func</code></a></h4>
 <p>Bind the socket to a specific network on the provided IP address and port.</p>

wit/network.wit

@@ -18,8 +18,6 @@ interface network {
     ///
     /// See each individual API for what the POSIX equivalents are. They sometimes differ per API.
     enum error-code {
-        // ### GENERAL ERRORS ###
-
         /// Unknown error
         unknown,
 
@@ -64,9 +62,6 @@ interface network {
         would-block,
 
 
-
-        // ### TCP & UDP SOCKET ERRORS ###
-
         /// The operation is not valid in the socket's current state.
         invalid-state,
 
@@ -83,24 +78,21 @@ interface network {
         remote-unreachable,
 
 
-        // ### TCP SOCKET ERRORS ###
-
-        /// The connection was forcefully rejected
+        /// The TCP connection was forcefully rejected
         connection-refused,
 
-        /// The connection was reset.
+        /// The TCP connection was reset.
         connection-reset,
 
-        /// A connection was aborted.
+        /// A TCP connection was aborted.
         connection-aborted,
 
 
-        // ### UDP SOCKET ERRORS ###
+        /// The size of a datagram sent to a UDP socket exceeded the maximum
+        /// supported size.
         datagram-too-large,
 
 
-        // ### NAME LOOKUP ERRORS ###
-
         /// Name does not exist or has no suitable associated IP addresses.
         name-unresolvable,
 
@@ -128,15 +120,21 @@ interface network {
     }
 
     record ipv4-socket-address {
-        port: u16, // sin_port
-        address: ipv4-address, // sin_addr
+        /// sin_port
+        port: u16,
+        /// sin_addr
+        address: ipv4-address,
     }
 
     record ipv6-socket-address {
-        port: u16, // sin6_port
-        flow-info: u32, // sin6_flowinfo
-        address: ipv6-address, // sin6_addr
-        scope-id: u32, // sin6_scope_id
+        /// sin6_port
+        port: u16,
+        /// sin6_flowinfo
+        flow-info: u32,
+        /// sin6_addr
+        address: ipv6-address,
+        /// sin6_scope_id
+        scope-id: u32,
     }
 
     variant ip-socket-address {