Skip to content

Commit

Permalink
Switch to /// comments. (#38)
Browse files Browse the repository at this point in the history 
* Switch to `///` comments.

Per the discussion in WebAssembly/component-model#286, remove some `//`
comments which had been intended as non-documentation comments to `///`
documentation comments.

* Update to the latest wasi-sockets and wasi-io.

Update to the latest wasi-sockets and wasi-io. The only changes are the
addition of some comments, and changing some comments from `//` to `///`.
  • Loading branch information
@sunfishcode
sunfishcode committed Jan 12, 2024
1 parent d67056b commit 87b8233
Show file tree
Hide file tree
Showing 8 changed files with 154 additions and 53 deletions.
8 changes: 4 additions & 4 deletions .github/workflows/main.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,15 @@ 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
curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.5/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
with:
wit-bindgen: '0.15.0'
wit-bindgen: '0.16.0'
worlds: "command imports"
60 changes: 51 additions & 9 deletions command.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,10 @@ 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>
<p>When the source of a <code>read</code> is binary data, the bytes from the source
are returned verbatim. When the source of a <code>read</code> is known to the
implementation to be text, bytes containing the UTF-8 encoding of the
text are returned.</p>
<p>This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to <code>len</code> bytes;
it may return fewer than requested, but not more. The list is
Expand Down Expand Up @@ -301,6 +305,11 @@ error.</p>
</ul>
<h4><a name="method_output_stream.write"><code>[method]output-stream.write: func</code></a></h4>
<p>Perform a write. This function never blocks.</p>
<p>When the destination of a <code>write</code> is binary data, the bytes from
<code>contents</code> are written verbatim. When the destination of a <code>write</code> is
known to the implementation to be text, the bytes of <code>contents</code> are
transcoded from UTF-8 into the encoding of the destination and then
written.</p>
<p>Precondition: check-write gave permit of Ok(n) and contents has a
length of less than or equal to n. Otherwise, this function will trap.</p>
<p>returns Err(closed) without writing if the stream has closed since
Expand Down Expand Up @@ -514,11 +523,19 @@ is ready for reading, before performing the <code>splice</code>.</p>
<li><a name="get_stderr.0"></a> own&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;</li>
</ul>
<h2><a name="wasi:cli_terminal_input_0.2.0_rc_2023_12_05">Import interface wasi:cli/terminal-input@0.2.0-rc-2023-12-05</a></h2>
<p>Terminal input.</p>
<p>In the future, this may include functions for disabling echoing,
disabling input buffering so that keyboard events are sent through
immediately, querying supported features, and so on.</p>
<hr />
<h3>Types</h3>
<h4><a name="terminal_input"><code>resource terminal-input</code></a></h4>
<p>The input side of a terminal.</p>
<h2><a name="wasi:cli_terminal_output_0.2.0_rc_2023_12_05">Import interface wasi:cli/terminal-output@0.2.0-rc-2023-12-05</a></h2>
<p>Terminal output.</p>
<p>In the future, this may include functions for querying the terminal
size, being notified of terminal size changes, querying supported
features, and so on.</p>
<hr />
<h3>Types</h3>
<h4><a name="terminal_output"><code>resource terminal-output</code></a></h4>
Expand Down Expand Up @@ -1659,18 +1676,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>
Expand Down Expand Up @@ -1726,16 +1745,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>
Expand Down Expand Up @@ -2313,6 +2350,11 @@ implicitly bind the socket.</p>
<li><code>not-in-progress</code>: A <code>bind</code> operation is not in progress.</li>
<li><code>would-block</code>: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)</li>
</ul>
<h1>Implementors note</h1>
<p>When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
and SO_REUSEADDR performs something different entirely.</p>
<h1>References</h1>
<ul>
<li><a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html">https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html</a></li>
Expand Down
60 changes: 51 additions & 9 deletions imports.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,10 @@ 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>
<p>When the source of a <code>read</code> is binary data, the bytes from the source
are returned verbatim. When the source of a <code>read</code> is known to the
implementation to be text, bytes containing the UTF-8 encoding of the
text are returned.</p>
<p>This function returns a list of bytes containing the read data,
when successful. The returned list will contain up to <code>len</code> bytes;
it may return fewer than requested, but not more. The list is
Expand Down Expand Up @@ -296,6 +300,11 @@ error.</p>
</ul>
<h4><a name="method_output_stream.write"><code>[method]output-stream.write: func</code></a></h4>
<p>Perform a write. This function never blocks.</p>
<p>When the destination of a <code>write</code> is binary data, the bytes from
<code>contents</code> are written verbatim. When the destination of a <code>write</code> is
known to the implementation to be text, the bytes of <code>contents</code> are
transcoded from UTF-8 into the encoding of the destination and then
written.</p>
<p>Precondition: check-write gave permit of Ok(n) and contents has a
length of less than or equal to n. Otherwise, this function will trap.</p>
<p>returns Err(closed) without writing if the stream has closed since
Expand Down Expand Up @@ -509,11 +518,19 @@ is ready for reading, before performing the <code>splice</code>.</p>
<li><a name="get_stderr.0"></a> own&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;</li>
</ul>
<h2><a name="wasi:cli_terminal_input_0.2.0_rc_2023_12_05">Import interface wasi:cli/terminal-input@0.2.0-rc-2023-12-05</a></h2>
<p>Terminal input.</p>
<p>In the future, this may include functions for disabling echoing,
disabling input buffering so that keyboard events are sent through
immediately, querying supported features, and so on.</p>
<hr />
<h3>Types</h3>
<h4><a name="terminal_input"><code>resource terminal-input</code></a></h4>
<p>The input side of a terminal.</p>
<h2><a name="wasi:cli_terminal_output_0.2.0_rc_2023_12_05">Import interface wasi:cli/terminal-output@0.2.0-rc-2023-12-05</a></h2>
<p>Terminal output.</p>
<p>In the future, this may include functions for querying the terminal
size, being notified of terminal size changes, querying supported
features, and so on.</p>
<hr />
<h3>Types</h3>
<h4><a name="terminal_output"><code>resource terminal-output</code></a></h4>
Expand Down Expand Up @@ -1654,18 +1671,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>
Expand Down Expand Up @@ -1721,16 +1740,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>
Expand Down Expand Up @@ -2308,6 +2345,11 @@ implicitly bind the socket.</p>
<li><code>not-in-progress</code>: A <code>bind</code> operation is not in progress.</li>
<li><code>would-block</code>: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)</li>
</ul>
<h1>Implementors note</h1>
<p>When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
and SO_REUSEADDR performs something different entirely.</p>
<h1>References</h1>
<ul>
<li><a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html">https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html</a></li>
Expand Down
8 changes: 4 additions & 4 deletions wit/deps.lock
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,8 @@ sha512 = "2c242489801a75466986fe014d730fb3aa7b5c6e56a230c8735e6672711b58bcbe92ba

[io]
url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz"
sha256 = "b622db2755978a49d18d35d84d75f66b2b1ed23d7bf413e5c9e152e190cc7d4b"
sha512 = "d19c9004e75bf3ebe3e34cff498c3d7fee04cd57a7fba7ed12a0c5ad842ba5715c009de77a152c57da0500f6ca0986b6791b6f022829bdd5a024f7bc114c2ff6"
sha256 = "7a3c644dfd434f77fdf3f3d3b3caaca9538a0ade785167a3cce0321609f9d4e1"
sha512 = "2888f12b91359d630b4270f60e3c78855d9b305274ebf8a5decaef8698a74cc85c426823dc708b393f461b85ad991711d7400c2b2a24795001db5aee3ae19c70"

[random]
url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz"
Expand All @@ -20,5 +20,5 @@ sha512 = "cc4fa3d178559a89d9d6a376e3359b892158d1e73317c5db1f797ebc6b0b57abf24227

[sockets]
url = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz"
sha256 = "b5c2e9cc87cefbaef06bbe9978f9bc336da9feee2d51747bc28e10164fc46c39"
sha512 = "3aea6fe0c768b27d5c5cb3adab5e60dc936198f8b677c2cf6c4d57a0460db87eb779e0b577f1240fb2a6bf3ade49919fbffe39b0137bce3242343e6091cc7510"
sha256 = "8bcfc6838515714d4bd6cbfb81bb2dd25c6d509c34d593fe6398a08ae825a0be"
sha512 = "85d23ff1478cd2bee5023c11ed75edaa918f14ad3f0d1142de88b3145a25189c40f4194421f1e234cc893091255c68e5b157e16682bcc5ae0993f78bed606504"
11 changes: 11 additions & 0 deletions wit/deps/io/streams.wit
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,11 @@ interface streams {
resource input-stream {
/// Perform a non-blocking read from the stream.
///
/// When the source of a `read` is binary data, the bytes from the source
/// are returned verbatim. When the source of a `read` is known to the
/// implementation to be text, bytes containing the UTF-8 encoding of the
/// text are returned.
///
/// This function returns a list of bytes containing the read data,
/// when successful. The returned list will contain up to `len` bytes;
/// it may return fewer than requested, but not more. The list is
Expand Down Expand Up @@ -111,6 +116,12 @@ interface streams {

/// Perform a write. This function never blocks.
///
/// When the destination of a `write` is binary data, the bytes from
/// `contents` are written verbatim. When the destination of a `write` is
/// known to the implementation to be text, the bytes of `contents` are
/// transcoded from UTF-8 into the encoding of the destination and then
/// written.
///
/// Precondition: check-write gave permit of Ok(n) and contents has a
/// length of less than or equal to n. Otherwise, this function will trap.
///
Expand Down
36 changes: 17 additions & 19 deletions wit/deps/sockets/network.wit
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,

Expand Down Expand Up @@ -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,

Expand All @@ -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,

Expand Down Expand Up @@ -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 {
Expand Down
6 changes: 6 additions & 0 deletions wit/deps/sockets/tcp.wit
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,12 @@ interface tcp {
/// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
/// - `not-in-progress`: A `bind` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
///
/// # Implementors note
/// When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
/// state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
/// socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
/// and SO_REUSEADDR performs something different entirely.
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
Expand Down
Loading

0 comments on commit 87b8233

Please sign in to comment.