emscripten-core / emscripten-core/emscripten
HTML5 Callbacks - add missing documentation for emscripten_html5_remove_all_event_listeners()
- Dominant language
- C++
- Stars
- 27.6k
- Forks
- 3.6k
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 105
Description
HTML5 callback assigning functions have a similar interface `emscripten_set_XX_callback()`:
```
emscripten_set_mousedown_callback
emscripten_set_mouseup_callback
emscripten_set_mousemove_callback
...
```
Function name suggests that callback will be **set** (and will **replace** previously set callback), but apparently it actually **appends** one more callback to the list (using methods like `addEventListener()`). The [documentation](https://emscripten.org/docs/api_reference/html5.h.html) is laconic in this context and uses "**register**" wording with non-obvious effect (at least to me):
> Registers a callback function for receiving browser-generated mouse input events.
It is proposed improving documentation to:
- Specify clearly "add" behavior of `emscripten_set_XX_callback`;
- Document `emscripten_html5_remove_all_event_listeners()`, the only way to remove already registered callbacks.
Probably the main concern is putting `emscripten_html5_remove_all_event_listeners()` (#7257) into documentation, as otherwise it is unclear how to reset callbacks and setup them anew...
Although `emscripten_set_` naming also looks confusing to me, but I guess it is not that trivial fixing implementation or/and renaming/extending existing API with `emscripten_add_XX_callback()` / `emscripten_remove_XX_callback()`.
Contributor guide
Assessment
This issue has not been assessed yet.