Merge pull request #237 from bytecodealliance/ydnar/tidy

all: tidy up documentation

Author: ydnar

CONTRIBUTING.md

@@ -10,14 +10,14 @@ Developing and testing this package requires an up-to-date installation of [Go](
 
 Tests are supported under both Go and TinyGo, on Linux, macOS, and WebAssembly.
 
-```sh
+```console
 go test ./...
 tinygo test ./...
 ```
 
 Testing with WebAssembly (`wasip1`) requires an installation of [`go_wasip1_wasm32_exec`](https://go.dev/blog/wasi) and [Wasmtime](https://wasmtime.dev). WASI 0.2 `wasip2` is supported under TinyGo version 0.33.0 or later.
 
-```sh
+```console
 GOARCH=wasm GOOS=wasip1 go test ./...
 GOARCH=wasm GOOS=wasip1 tinygo test ./...
 tinygo test -target=wasip2 ./... # requires TinyGo 0.33.0 or later

README.md

@@ -1,17 +1,16 @@
 # go.bytecodealliance.org
 
-[![pkg.go.dev](https://img.shields.io/badge/docs-pkg.go.dev-blue.svg)](https://pkg.go.dev/go.bytecodealliance.org) [![build status](https://img.shields.io/github/actions/workflow/status/bytecodealliance/go-modules/test.yaml?branch=main)](https://github.com/bytecodealliance/go-modules/actions)
-
+[WebAssembly](https://webassembly.org), [WASI](https://wasi.dev), and [Component Model](https://component-model.bytecodealliance.org/) modules for [Go](https://go.dev) and [TinyGo](https://tinygo.org).
 
-A monorepo of [WebAssembly](https://webassembly.org), [WASI](https://wasi.dev), and [Component Model](https://component-model.bytecodealliance.org/) modules for [Go](https://go.dev) and [TinyGo](https://tinygo.org).
+[![pkg.go.dev](https://img.shields.io/badge/docs-pkg.go.dev-blue.svg)](https://pkg.go.dev/go.bytecodealliance.org) [![build status](https://img.shields.io/github/actions/workflow/status/bytecodealliance/go-modules/test.yaml?branch=main)](https://github.com/bytecodealliance/go-modules/actions)
 
 ## About
 
-This repository contains code to generate Go bindings for [Component Model](https://component-model.bytecodealliance.org/) interfaces defined in [WIT](https://component-model.bytecodealliance.org/design/wit.html) (WebAssembly Interface Type) files. A goal of this project is to accelerate adoption of the Component Model and development of [WASI 0.2+](https://bytecodealliance.org/articles/WASI-0.2) in Go.
+Package `wit/bindgen` contains code to generate Go bindings for [Component Model](https://component-model.bytecodealliance.org/) interfaces defined in [WIT](https://component-model.bytecodealliance.org/design/wit.html) (WebAssembly Interface Type) files. A goal of this project is to accelerate adoption of the Component Model and development of [WASI 0.2+](https://bytecodealliance.org/articles/WASI-0.2) in Go.
 
 ### Component Model
 
-Package [cm](./cm) contains helper types and functions used by generated packages, such as `option<t>`, `result<ok, err>`, `variant`, `list`, and `resource`. These are intended for use by generated [Component Model](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions) bindings, where the caller converts to a Go equivalent. It attempts to map WIT semantics to their equivalent in Go where possible.
+Package `cm` contains helper types and functions used by generated packages, such as `option<t>`, `result<ok, err>`, `variant`, `list`, and `resource`. These are intended for use by generated [Component Model](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions) bindings, where the caller converts to a Go equivalent. It attempts to map WIT semantics to their equivalent in Go where possible.
 
 #### Note on Memory Safety
 
@@ -23,41 +22,41 @@ Package `cm` and generated bindings from `wit-bindgen-go` may have compatibility
 
 The `wit-bindgen-go` tool can generate Go bindings for WIT interfaces and worlds. If [`wasm-tools`](https://crates.io/crates/wasm-tools) is installed and in `$PATH`, then `wit-bindgen-go` can load WIT directly.
 
-```sh
+```console
 wit-bindgen-go generate ../wasi-cli/wit
 ```
 
 Otherwise, pass the JSON representation of a fully-resolved WIT package:
 
-```sh
+```console
 wit-bindgen-go generate wasi-cli.wit.json
 ```
 
 Or pipe via `stdin`:
 
-```sh
+```console
 wasm-tools component wit -j --all-features ../wasi-cli/wit | wit-bindgen-go generate
 ```
 
 ### JSON → WIT
 
 For debugging purposes, `wit-bindgen-go` can also convert a JSON representation back into WIT. This is useful for validating that the intermediate representation faithfully represents the original WIT source.
 
-```sh
+```console
 wit-bindgen-go wit example.wit.json
 ```
 
 ### WIT → JSON
 
-The [wit](./wit) package can decode a JSON representation of a fully-resolved WIT file. Serializing WIT into JSON requires [wasm-tools](https://crates.io/crates/wasm-tools) v1.210.0 or higher. To convert a WIT file into JSON, run `wasm-tools` with the `-j` argument:
+Package `wit` can decode a JSON representation of a fully-resolved WIT file. Serializing WIT into JSON requires [wasm-tools](https://crates.io/crates/wasm-tools) v1.210.0 or higher. To convert a WIT file into JSON, run `wasm-tools` with the `-j` argument:
 
-```sh
+```console
 wasm-tools component wit -j --all-features example.wit
 ```
 
 This will emit JSON on `stdout`, which can be piped to a file or another program.
 
-```sh
+```console
 wasm-tools component wit -j --all-features example.wit > example.wit.json
 ```
 

RELEASE.md

@@ -2,20 +2,21 @@
 
 This document describes the steps to release a new version of the `wit-bindgen-go` CLI.
 
-## 1. Update the [CHANGELOG.md](./CHANGELOG.md)
+## 1. Update [CHANGELOG.md](./CHANGELOG.md)
 
-* Add the latest changes to CHANGELOG.md.
-* Rename the Unreleased section to reflect the new version number.
-	* Update the links to new version tag in the footer of CHANGELOG.md
-* Submit a pull request (PR) with these updates.
+1. Add the latest changes to [CHANGELOG.md](./CHANGELOG.md).
+1. Rename the Unreleased section to reflect the new version number.
+	1. Update the links to new version tag in the footer of CHANGELOG.md
+1. Add today’s date (YYYY-MM-DD) after an em dash (—).
+1. Submit a [GitHub Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) with these updates.
 
 ## 2. Create a new release
 
 Once the PR is merged, tag the new version in Git and push the tag to GitHub.
 
 For example, to tag version `v0.3.0`:
 
-```sh
+```console
 git tag v0.3.0
 git push origin v0.3.0
 ```

cm/docs.go

@@ -1,4 +1,4 @@
-// Package cm contains types and functions for interfacing with the WebAssembly Component Model.
+// Package cm provides types and functions for interfacing with the WebAssembly Component Model.
 //
 // The types in this package (such as [List], [Option], [Result], and [Variant]) are designed to match the memory layout
 // of [Component Model] types as specified in the [Canonical ABI].

wit/docs.go

@@ -1,5 +1,11 @@
-// Package wit contains a Go representation of the WIT ([WebAssembly Interface Type])
-// specification as defined in the [WebAssembly Component Model].
+// Package wit contains a Go representation of the WIT (WebAssembly Interface Type) specification.
+//
+// # WIT
+//
+// WIT ([WebAssembly Interface Type]) is an interface definition language with rich types, functions, and methods,
+// used to define the interface of a [Component].
+//
+// Note: this package depends on the [wasm-tools] exectuable to parse WIT into an intermediary JSON representation.
 //
 // # Structure
 //
@@ -29,9 +35,9 @@
 //
 //	// Do something with res
 //
-// [WebAssembly Interface Type]: https://component-model.bytecodealliance.org/design/wit.html
-// [WebAssembly Component Model]: https://component-model.bytecodealliance.org/introduction.html
 // [wit-parser]: https://docs.rs/wit-parser/latest/wit_parser/
 // [source]: https://github.com/bytecodealliance/wasm-tools/tree/main/crates/wit-parser
 // [wasm-tools]: https://crates.io/crates/wasm-tools
+// [WebAssembly Interface Type]: https://component-model.bytecodealliance.org/design/wit.html
+// [Component]: https://component-model.bytecodealliance.org/introduction.html
 package wit

x/cabi/README.md

@@ -0,0 +1,19 @@
+// Package cabi contains a single WebAssembly function exported as cabi_realloc.
+//
+// To use, import this package with _:
+//
+//	import _ "go.bytecodealliance.org/x/cabi"
+//
+// Function realloc is a WebAssembly [core function] that is validated to have the following core function type:
+//
+//	(func (param $originalPtr i32)
+//	      (param $originalSize i32)
+//	      (param $alignment i32)
+//	      (param $newSize i32)
+//	      (result i32))
+//
+// The [Canonical ABI] will use realloc both to allocate (passing 0 for the first two parameters) and reallocate. If the Canonical ABI needs realloc, validation requires this option to be present (there is no default).
+//
+// [core function]: https://www.w3.org/TR/wasm-core-2/syntax/modules.html#functions
+// [Canonical ABI]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/CanonicalABI.md
+package cabi