godoc: moves sealed type notes to the top and backfills where missing (#1397)

wazero uses interfaces even when they aren't intended to be implemented
by users. We relied on documentation, to suggest what is implementable,
and in some cases documented correctly types that weren't for
implementation.

However, we didn't add that boilerplate to all types, and we also forgot
to recently when it was discussed a week or two ago. This finishes the
job by boilerplating all types that aren't for implementation. This also
orders to the top when it already existed.

Later, we can choose to enforce by type as well, we didn't know how to
do that before. Basically before we just casted to our internal types,
which would stop accidental implementation for things except people
using the types for wrapping purposes.

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

api/wasm.go

@@ -135,8 +135,9 @@ func ValueTypeName(t ValueType) string {
 //
 // # Notes
 //
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 //   - Closing the wazero.Runtime closes any Module it instantiated.
-//   - This is an interface for decoupling, not third-party implementations. All implementations are in wazero.
 type Module interface {
 	fmt.Stringer
 
@@ -189,6 +190,11 @@ type Module interface {
 }
 
 // Closer closes a resource.
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type Closer interface {
 	// Close closes the resource.
 	//
@@ -202,6 +208,11 @@ type Closer interface {
 // (wazero.CompiledModule).
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#exports%E2%91%A0
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type ExportDefinition interface {
 	// ModuleName is the possibly empty name of the module defining this
 	// export.
@@ -231,6 +242,11 @@ type ExportDefinition interface {
 // (wazero.CompiledModule). Units are in pages (64KB).
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#exports%E2%91%A0
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type MemoryDefinition interface {
 	ExportDefinition
 
@@ -246,6 +262,11 @@ type MemoryDefinition interface {
 // (wazero.CompiledModule).
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#exports%E2%91%A0
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type FunctionDefinition interface {
 	ExportDefinition
 
@@ -303,6 +324,11 @@ type FunctionDefinition interface {
 // (wazero.Runtime InstantiateModule).
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#syntax-func
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type Function interface {
 	// Definition is metadata about this function from its defining module.
 	Definition() FunctionDefinition
@@ -426,6 +452,11 @@ func (f GoFunc) Call(ctx context.Context, stack []uint64) {
 //	}
 //
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#globals%E2%91%A0
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type Global interface {
 	fmt.Stringer
 
@@ -439,6 +470,11 @@ type Global interface {
 }
 
 // MutableGlobal is a Global whose value can be updated at runtime (variable).
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type MutableGlobal interface {
 	Global
 
@@ -450,12 +486,13 @@ type MutableGlobal interface {
 
 // Memory allows restricted access to a module's memory. Notably, this does not allow growing.
 //
+// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#storage%E2%91%A0
+//
 // # Notes
 //
-//   - This is an interface for decoupling, not third-party implementations. All implementations are in wazero.
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 //   - This includes all value types available in WebAssembly 1.0 (20191205) and all are encoded little-endian.
-//
-// See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#storage%E2%91%A0
 type Memory interface {
 	// Definition is metadata about this memory from its defining module.
 	Definition() MemoryDefinition
@@ -573,6 +610,11 @@ type Memory interface {
 }
 
 // CustomSection contains the name and raw data of a custom section.
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type CustomSection interface {
 	// Name is the name of the custom section
 	Name() string

builder.go

@@ -32,6 +32,11 @@ import (
 //		x, _ := m.Memory().ReadUint32Le(ctx, offset)
 //		return x
 //	}
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type HostFunctionBuilder interface {
 	// WithGoFunction is an advanced feature for those who need higher
 	// performance than WithFunc at the cost of more complexity.
@@ -166,6 +171,8 @@ type HostFunctionBuilder interface {
 //
 // # Notes
 //
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 //   - HostModuleBuilder is mutable: each method returns the same instance for
 //     chaining.
 //   - methods do not return errors, to allow chaining. Any validation errors

cache.go

@@ -18,7 +18,12 @@ import (
 
 // CompilationCache reduces time spent compiling (Runtime.CompileModule) the same wasm module.
 //
-// Instances of this can be reused across multiple runtimes, if configured via RuntimeConfig.
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
+//   - Instances of this can be reused across multiple runtimes, if configured
+//     via RuntimeConfig.
 type CompilationCache interface{ api.Closer }
 
 // NewCompilationCache returns a new CompilationCache to be passed to RuntimeConfig.

config.go

@@ -28,8 +28,12 @@ import (
 //
 //	rConfig = wazero.NewRuntimeConfig().WithCoreFeatures(api.CoreFeaturesV1)
 //
-// Note: RuntimeConfig is immutable. Each WithXXX function returns a new
+// # Notes
-// instance including the corresponding change.
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
+//   - RuntimeConfig is immutable. Each WithXXX function returns a new instance
+//     including the corresponding change.
 type RuntimeConfig interface {
 	// WithCoreFeatures sets the WebAssembly Core specification features this
 	// runtime supports. Defaults to api.CoreFeaturesV2.
@@ -293,7 +297,11 @@ func (c *runtimeConfig) WithCustomSections(storeCustomSections bool) RuntimeConf
 // the name "Module" for both before and after instantiation as the name conflation has caused confusion.
 // See https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#semantic-phases%E2%91%A0
 //
-// Note: Closing the wazero.Runtime closes any CompiledModule it compiled.
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
+//   - Closing the wazero.Runtime closes any CompiledModule it compiled.
 type CompiledModule interface {
 	// Name returns the module name encoded into the binary or empty if not.
 	Name() string
@@ -423,7 +431,12 @@ func (c *customSection) Data() []byte {
 // While wazero supports Windows as a platform, host functions using ModuleConfig follow a UNIX dialect.
 // See RATIONALE.md for design background and relationship to WebAssembly System Interfaces (WASI).
 //
-// Note: ModuleConfig is immutable. Each WithXXX function returns a new instance including the corresponding change.
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
+//   - ModuleConfig is immutable. Each WithXXX function returns a new instance
+//     including the corresponding change.
 type ModuleConfig interface {
 	// WithArgs assigns command-line arguments visible to an imported function that reads an arg vector (argv). Defaults to
 	// none. Runtime.InstantiateModule errs if any arg is empty.

fsconfig.go

@@ -56,6 +56,8 @@ import (
 //
 // # Notes
 //
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 //   - FSConfig is immutable. Each WithXXX function returns a new instance
 //     including the corresponding change.
 //   - RATIONALE.md includes design background and relationship to WebAssembly

imports/assemblyscript/assemblyscript.go

@@ -71,6 +71,11 @@ func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error) {
 
 // FunctionExporter configures the functions in the "env" module used by
 // AssemblyScript.
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type FunctionExporter interface {
 	// WithAbortMessageDisabled configures the AssemblyScript abort function to
 	// discard any message.

imports/emscripten/emscripten.go

@@ -49,6 +49,11 @@ func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error) {
 
 // FunctionExporter configures the functions in the "env" module used by
 // Emscripten.
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type FunctionExporter interface {
 	// ExportFunctions builds functions to export with a wazero.HostModuleBuilder
 	// named "env".

imports/wasi_snapshot_preview1/wasi.go

@@ -57,6 +57,11 @@ func Instantiate(ctx context.Context, r wazero.Runtime) (api.Closer, error) {
 }
 
 // Builder configures the ModuleName module for later use via Compile or Instantiate.
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type Builder interface {
 	// Compile compiles the ModuleName module. Call this before Instantiate.
 	//
@@ -94,6 +99,11 @@ func (b *builder) Instantiate(ctx context.Context) (api.Closer, error) {
 }
 
 // FunctionExporter exports functions into a wazero.HostModuleBuilder.
+//
+// # Notes
+//
+//   - This is an interface for decoupling, not third-party implementations.
+//     All implementations are in wazero.
 type FunctionExporter interface {
 	ExportFunctions(wazero.HostModuleBuilder)
 }

runtime.go

@@ -25,9 +25,9 @@ import (
 //
 // # Notes
 //
-//   - Closing this closes any CompiledModule or Module it instantiated.
 //   - This is an interface for decoupling, not third-party implementations.
 //     All implementations are in wazero.
+//   - Closing this closes any CompiledModule or Module it instantiated.
 type Runtime interface {
 	// Instantiate instantiates a module from the WebAssembly binary (%.wasm)
 	// with default configuration.