From 37088bf3821eb7cb2bf119e20210d9a41909746a Mon Sep 17 00:00:00 2001
From: Chan Wen Xu <lutherchanpublic@gmail.com>
Date: Sun, 21 Mar 2021 20:29:31 +0800
Subject: [PATCH] docs: Document unexported functions

Some unexported functions are non-trivial and may be confusing. This
commit clarifies their use.
---
 wasm/function.go     | 11 +++++++++++
 wasm/reflect_from.go |  2 ++
 wasm/reflect_to.go   |  3 +++
 3 files changed, 16 insertions(+)

diff --git a/wasm/function.go b/wasm/function.go
index 5256c3b..a509c85 100644
--- a/wasm/function.go
+++ b/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:
diff --git a/wasm/reflect_from.go b/wasm/reflect_from.go
index 6fe4039..8b119b7 100644
--- a/wasm/reflect_from.go
+++ b/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")
diff --git a/wasm/reflect_to.go b/wasm/reflect_to.go
index fa94c4f..bf6a271 100644
--- a/wasm/reflect_to.go
+++ b/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 {