Web backend refactor and documentation (#1415)

The current implementation of the event loop runner has some significant
problems. It can't handle multiple events being emitted at once (for
example, when a keyboard event causes a key input, a text input, and a
modifier change.) It's also relatively easy to introduce bugs for the
different possible control flow states.

The new model separates intentionally emitting a NewEvents (poll
completed, wait completed, init) and emitting a normal event, as well as
providing a method for emitting multiple events in a single call.

src/platform_impl/web/mod.rs

@@ -1,3 +1,22 @@
+// Brief introduction to the internals of the web backend:
+// Currently, the web backend supports both wasm-bindgen and stdweb as methods of binding to the
+// environment. Because they are both supporting the same underlying APIs, the actual web bindings
+// are cordoned off into backend abstractions, which present the thinnest unifying layer possible.
+//
+// When adding support for new events or interactions with the browser, first consult trusted
+// documentation (such as MDN) to ensure it is well-standardised and supported across many browsers.
+// Once you have decided on the relevant web APIs, add support to both backends.
+//
+// The backend is used by the rest of the module to implement Winit's business logic, which forms
+// the rest of the code. 'device', 'error', 'monitor', and 'window' define web-specific structures
+// for winit's cross-platform structures. They are all relatively simple translations.
+//
+// The event_loop module handles listening for and processing events. 'Proxy' implements
+// EventLoopProxy and 'WindowTarget' implements EventLoopWindowTarget. WindowTarget also handles
+// registering the event handlers. The 'Execution' struct in the 'runner' module handles taking
+// incoming events (from the registered handlers) and ensuring they are passed to the user in a
+// compliant way.
+
 mod device;
 mod error;
 mod event_loop;