For asking questions about the language, see one of our forums: https://golang.org/wiki/Questions It is not completely clear to me whether this is a documentation bug or a question about correct usage.

/cc @bradfitz @neelance who may be able to better assist.

This works fine for me. The code I tested:

package main

import (
	"fmt"
	"syscall/js"
)

func main() {
	outerDiv := js.Global().Get("document").Call("getElementById", "outer")
	innerDiv := js.Global().Get("document").Call("getElementById", "inner")

	outerDiv.Call("addEventListener", "click", js.FuncOf(func(this js.Value, args []js.Value) interface{} {
		fmt.Println("outer listener called")
		return nil
	}))
	innerDiv.Call("addEventListener", "click", js.FuncOf(func(this js.Value, args []js.Value) interface{} {
		args[0].Call("stopPropagation")
		fmt.Println("inner listener called")
		return nil
	}))

	select {}
}

@neelance thx for the example. I found my fault: I passed a wrong additional parameter to addEventListener which evaluated to true and is then interpreted as the useCapture flag, which caused a "wrong" event bubbling, as specified in https://developer.mozilla.org/de/docs/Web/API/EventTarget/addEventListener

However regarding the documentation of js.Func, I propose a small change like the following to be a bit more explicit:

A wrapped function triggered by JavaScript's event loop gets executed on an extra goroutine, however the event loop waits until the goroutine returns. Therefore blocking operations in the wrapped function should explicitly start a new goroutine.

Otherwise this ticket can be closed.

Current doc:

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.

Proposed doc:

A wrapped function triggered by JavaScript's event loop gets executed on an extra goroutine, however the event loop waits until the goroutine returns. Therefore blocking operations in the wrapped function should explicitly start a new goroutine.

@torbenschinke Could you please give me some more detail on the reasons for your change? Doing any blocking operation directly in the wrapped function most likely results in a "deadlock" error. For this result, "the event loop waits until the goroutine returns" sounds a bit too innocent. :)

@neelance The facts of the current documentation are not particularly coupled with each other. Each fact is correct, but because there is no specific logical glue between them, it is difficult to me to create a sufficient mental model, which is needed to understand a specific behavior.

For example, the statement that each wrapped function, which is called by JavaScript's event loop, gets executed on an extra goroutine is clear, but as long as the context is not described further, it makes it hard to understand consequences: for a gopher it is a surprise that a function can get executed on a goroutine which will block the callee, without using channels, waitgroups or mutexes.

Next, the statement about blocking operations is probably also correct. But what exactly is a blocking operation? Is it only related to epoll-like I/O operations or even a tight for-loop or is it calling syscall/js APIs?

Without these information, it seems very hard to anticipate the actual behavior and (expected) side effects of doing I/O (like causing deadlocks) or synchronous calls into Javascript (like stopping propagation).

I agree that we should try to make this as easily understandable as possible.

The statement about waiting for the function to return is actually a bit earlier in the documentation:

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.

Maybe this "synchronously" is not enough. Do you have any suggestion on how we can amend this part?

I looked through some of your CLs and the js-Transport-RoundTripper and it looks quite complex in detail, so please correct me, if I got something wrong. But here is my attempt:

// add the intent: why do we want to use FuncOf?
FuncOf registers a function to be used by JavaScript.

// perhaps better at the beginning of the documentation, not that readers gave up reading to early
Func.Release must be called to free up resources when the function
will not be used any more.

// explain the in and out arguments
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.

// now we can focus on explaining the lifecycle
Invoking the wrapped Go function from JavaScript will
pause the event loop and spawns a new go routine.
Other wrapped functions which are triggered during a call from Go to JavaScript
gets executed on the same goroutine.

// explain the consequences of that lifecycle
As a consequence, if one wrapped function blocks, JavaScript's event loop
is blocked until that func 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.

This is great, I like it a lot! Would you mind opening a CL or pull request for the change?

Change https://golang.org/cl/197458 mentions this issue: syscall/js: improve documentation of js.FuncOf