examples: polishes a few docs (#501)

Signed-off-by: Adrian Cole <adrian@tetrate.io>

examples/allocation/rust/greet.go

@@ -26,8 +26,8 @@ func main() {
 	// Create a new WebAssembly Runtime.
 	r := wazero.NewRuntime()
 
-	// Instantiate a module named "env" that exports a function to log a string
-	// to the console.
+	// Instantiate a Go-defined module named "env" that exports a function to
+	// log to the console.
 	env, err := r.NewModuleBuilder("env").
 		ExportFunction("log", logString).
 		Instantiate(ctx)
@@ -36,15 +36,15 @@ func main() {
 	}
 	defer env.Close()
 
-	// Instantiate a module named "greet" that imports the "log" function
-	// defined in "env".
+	// Instantiate a WebAssembly module that imports the "log" function defined
+	// in "env" and exports "memory" and functions we'll use in this example.
 	mod, err := r.InstantiateModuleFromCode(ctx, greetWasm)
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer mod.Close()
 
-	// Get a references to functions we'll use in this example.
+	// Get references to WebAssembly functions we'll use in this example.
 	greet := mod.ExportedFunction("greet")
 	greeting := mod.ExportedFunction("greeting")
 	allocate := mod.ExportedFunction("allocate")

examples/allocation/rust/testdata/src/lib.rs

@@ -80,8 +80,8 @@ unsafe fn ptr_to_string(ptr: u32, len: u32) -> String {
     return String::from(utf8);
 }
 
-/// Returns a pointer and size pair for the given string in a way that is
-/// compatible with WebAssembly numeric types.
+/// Returns a pointer and size pair for the given string in a way compatible
+/// with WebAssembly numeric types.
 ///
 /// Note: This doesn't change the ownership of the String. To intentionally
 /// leak it, use [`std::mem::forget`] on the input after calling this.

examples/allocation/tinygo/greet.go

@@ -27,8 +27,8 @@ func main() {
 	// Create a new WebAssembly Runtime.
 	r := wazero.NewRuntime()
 
-	// Instantiate a module named "env" that exports a function to log a string
-	// to the console.
+	// Instantiate a Go-defined module named "env" that exports a function to
+	// log to the console.
 	env, err := r.NewModuleBuilder("env").
 		ExportFunction("log", logString).
 		Instantiate(ctx)
@@ -45,15 +45,15 @@ func main() {
 	}
 	defer wm.Close()
 
-	// Instantiate a module named "greet" that imports the "log" function
-	// defined in "env".
+	// Instantiate a WebAssembly module that imports the "log" function defined
+	// in "env" and exports "memory" and functions we'll use in this example.
 	mod, err := r.InstantiateModuleFromCode(ctx, greetWasm)
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer mod.Close()
 
-	// Get a references to functions we'll use in this example.
+	// Get references to WebAssembly functions we'll use in this example.
 	greet := mod.ExportedFunction("greet")
 	greeting := mod.ExportedFunction("greeting")
 	// These are undocumented, but exported. See tinygo-org/tinygo#2788

examples/allocation/tinygo/testdata/greet.go

@@ -33,19 +33,19 @@ func greeting(name string) string {
 	return fmt.Sprint("Hello, ", name, "!")
 }
 
-// _greet is a WebAssembly export that accepts a string pointer (linear
-// memory offset) and calls greet.
+// _greet is a WebAssembly export that accepts a string pointer (linear memory
+// offset) and calls greet.
 //export greet
 func _greet(ptr, size uint32) {
 	name := ptrToString(ptr, size)
 	greet(name)
 }
 
-// _greet is a WebAssembly export that accepts a string pointer (linear
-// memory offset) and returns a pointer/size pair packed into a uint64.
+// _greet is a WebAssembly export that accepts a string pointer (linear memory
+// offset) and returns a pointer/size pair packed into a uint64.
 //
-// Note: This uses a uint64 instead of two result values for compatibility
-// with WebAssembly 1.0.
+// Note: This uses a uint64 instead of two result values for compatibility with
+// WebAssembly 1.0.
 //export greeting
 func _greeting(ptr, size uint32) (ptrSize uint64) {
 	name := ptrToString(ptr, size)
@@ -54,8 +54,8 @@ func _greeting(ptr, size uint32) (ptrSize uint64) {
 	return (uint64(ptr) << uint64(32)) | uint64(size)
 }
 
-// ptrToString returns a string from WebAssembly compatible numeric
-// types representing its pointer and length.
+// ptrToString returns a string from WebAssembly compatible numeric types
+// representing its pointer and length.
 func ptrToString(ptr uint32, size uint32) (ret string) {
 	// Here, we want to get a string represented by the ptr and size. If we
 	// wanted a []byte, we'd use reflect.SliceHeader instead.
@@ -65,8 +65,8 @@ func ptrToString(ptr uint32, size uint32) (ret string) {
 	return
 }
 
-// stringToPtr returns a pointer and size pair for the given string
-// in a way that is compatible with WebAssembly numeric types.
+// stringToPtr returns a pointer and size pair for the given string in a way
+// compatible with WebAssembly numeric types.
 func stringToPtr(s string) (uint32, uint32) {
 	buf := []byte(s)
 	ptr := &buf[0]

examples/import-go/age-calculator.go

@@ -23,8 +23,8 @@ func main() {
 	// Create a new WebAssembly Runtime.
 	r := wazero.NewRuntime()
 
-	// Instantiate a module named "env" that exports functions to get the
-	// current year and log to the console.
+	// Instantiate a Go-defined module named "env" that exports functions to
+	// get the current year and log to the console.
 	//
 	// Note: As noted on ExportFunction documentation, function signatures are
 	// constrained to a subset of numeric types.
@@ -46,8 +46,8 @@ func main() {
 	}
 	defer env.Close()
 
-	// Instantiate a module named "age-calculator" that imports functions
-	// defined in "env".
+	// Instantiate a WebAssembly module named "age-calculator" that imports
+	// functions defined in "env".
 	//
 	// Note: The import syntax in both Text and Binary format is the same
 	// regardless of if the function was defined in Go or WebAssembly.

examples/replace-import/README.md

@@ -1,3 +1,4 @@
 ## Replace import example
 
-This example shows how to override a module name hard-coded in a WebAssembly module.
+This example shows how to override a module name hard-coded in a WebAssembly
+module. This is similar to what some tools call "linking".

examples/replace-import/replace-import.go

@@ -10,7 +10,8 @@ import (
 	"github.com/tetratelabs/wazero/api"
 )
 
-// main shows how you can replace a module import when it doesn't match instantiated modules.
+// main shows how to override a module or function name hard-coded in a
+// WebAssembly module. This is similar to what some tools call "linking".
 func main() {
 	// Choose the context to use for function calls.
 	ctx := context.Background()
@@ -18,7 +19,8 @@ func main() {
 	// Create a new WebAssembly Runtime.
 	r := wazero.NewRuntime()
 
-	// Instantiate a function that closes the module under "assemblyscript.abort".
+	// Instantiate a Go-defined module named "assemblyscript" that exports a
+	// function to close the module that calls "abort".
 	host, err := r.NewModuleBuilder("assemblyscript").
 		ExportFunction("abort", func(m api.Module, messageOffset, fileNameOffset, line, col uint32) {
 			_ = m.CloseWithExitCode(255)
@@ -28,7 +30,7 @@ func main() {
 	}
 	defer host.Close()
 
-	// Compile code that needs the function "env.abort".
+	// Compile WebAssembly code that needs the function "env.abort".
 	code, err := r.CompileModule(ctx, []byte(`(module $needs-import
 	(import "env" "abort" (func $~lib/builtins/abort (param i32 i32 i32 i32)))
 
@@ -39,7 +41,8 @@ func main() {
 	}
 	defer code.Close()
 
-	// Instantiate the module, replacing the import "env.abort" with "assemblyscript.abort".
+	// Instantiate the WebAssembly module, replacing the import "env.abort"
+	// with "assemblyscript.abort".
 	mod, err := r.InstantiateModuleWithConfig(ctx, code, wazero.NewModuleConfig().
 		WithImport("env", "abort", "assemblyscript", "abort"))
 	if err != nil {