syscall/js: improve documentation of js.FuncOf

The existing documentation is improved to be more
explicit about the lifecycle and its consequences.

Fixes #34324

Change-Id: I9969afc69f6eeb7812c11fe821a842794df5aa5b
GitHub-Last-Rev: 246a4991660927f88f48290580e96b15c16663c1
GitHub-Pull-Request: golang/go#34551
Reviewed-on: https://go-review.googlesource.com/c/go/+/197458


Reviewed-by: Richard Musiol <neelance@gmail.com>

src/syscall/js/func.go

@@ -22,17 +22,22 @@ type Func struct {
 	id    uint32
 }
 
-// FuncOf returns a wrapped function.
+// FuncOf returns a function to be used by JavaScript.
 //
-// Invoking the JavaScript function will synchronously call the Go function fn with the value of JavaScript's
-// "this" keyword and the arguments of the invocation.
-// The return value of the invocation is the result of the Go function mapped back to JavaScript according to ValueOf.
+// The Go function fn is called with the value of JavaScript's "this" keyword and the
+// arguments of the invocation. The return value of the invocation is
+// the result of the Go function mapped back to JavaScript according to ValueOf.
 //
-// A wrapped function triggered during a call from Go to JavaScript gets executed on the same goroutine.
-// A wrapped function triggered by JavaScript's event loop gets executed on an extra goroutine.
-// Blocking operations in the wrapped function will block the event loop.
-// As a consequence, if one wrapped function blocks, other wrapped funcs will not be processed.
-// A blocking function should therefore explicitly start a new goroutine.
+// Invoking the wrapped Go function from JavaScript will
+// pause the event loop and spawn a new goroutine.
+// Other wrapped functions which are triggered during a call from Go to JavaScript
+// get executed on the same goroutine.
+//
+// As a consequence, if one wrapped function blocks, JavaScript's event loop
+// is blocked until that function returns. Hence, calling any async JavaScript
+// API, which requires the event loop, like fetch (http.Client), will cause an
+// immediate deadlock. Therefore a blocking function should explicitly start a
+// new goroutine.
 //
 // Func.Release must be called to free up resources when the function will not be used any more.
 func FuncOf(fn func(this Value, args []Value) interface{}) Func {