docs: Document unexported functions

Some unexported functions are non-trivial and may be confusing. This
commit clarifies their use.

wasm/function.go

@@ -16,6 +16,10 @@ type goThrowable struct {
 	Error  js.Value `wasm:"error"`
 }
 
+// toJSFunc takes a reflect.Value of a Go function and converts it to a JS function that:
+// Errors if the parameter types do not conform to the Go function signature,
+// Throws an error if the last returned value is an error and is non-nil,
+// Return an array if there's multiple non-error return values.
 func toJSFunc(x reflect.Value) js.Value {
 	funcType := x.Type()
 	var hasError bool
@@ -53,6 +57,8 @@ func toJSFunc(x reflect.Value) js.Value {
 
 var jsValueType = reflect.TypeOf(js.Value{})
 
+// conformJSValueToType attempts to convert the provided JS values to reflect.Values that match the
+// types expected for the parameters of funcType.
 func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Value) ([]reflect.Value, error) {
 	if funcType.NumIn() == 0 {
 		if len(values) != 0 {
@@ -62,6 +68,7 @@ func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Valu
 	}
 
 	if funcType.In(0) == jsValueType {
+		// If the first parameter is a js.Value, it is assumed to be the value of `this`.
 		values = append([]js.Value{this}, values...)
 	}
 
@@ -88,6 +95,10 @@ func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Valu
 	return in, nil
 }
 
+// returnValue wraps returned values by Go in a JS-friendly way.
+// If there are no returned values, it returns undefined.
+// If there is exactly one, it returns the JS equivalent.
+// If there is more than one, it returns an array containing the JS equivalent of every returned value.
 func returnValue(x []reflect.Value) js.Value {
 	switch len(x) {
 	case 0:

wasm/reflect_from.go

@@ -5,6 +5,8 @@ import (
 	"syscall/js"
 )
 
+// FromJSValue converts a given js.Value to the Go equivalent.
+// The new value of 'out' is undefined if FromJSValue returns an error.
 func FromJSValue(x js.Value, out interface{}) error {
 	// TODO
 	return fmt.Errorf("unimplemented")

wasm/reflect_to.go

@@ -71,6 +71,7 @@ func ToJSValue(x interface{}) js.Value {
 	}
 }
 
+// toJSArray converts the provided array or slice to a JS array.
 func toJSArray(x reflect.Value) js.Value {
 	arrayConstructor, err := Global().Get("Array")
 	if err != nil {
@@ -85,6 +86,7 @@ func toJSArray(x reflect.Value) js.Value {
 	return array
 }
 
+// mapToJSObject converts the provided map to a JS object.
 func mapToJSObject(x reflect.Value) js.Value {
 	objectConstructor, err := Global().Get("Object")
 	if err != nil {
@@ -134,6 +136,7 @@ func mapToJSObject(x reflect.Value) js.Value {
 	return obj
 }
 
+// structToJSObject converts a struct to a JS object.
 func structToJSObject(x reflect.Value) js.Value {
 	objectConstructor, err := Global().Get("Object")
 	if err != nil {