On wasm, provide intradoc-link for spawn() function in EventLoop …

…docs

And on any other platform, emit a footnote explaining that this function
is only available on wasm.

src/event_loop.rs

@@ -224,14 +224,26 @@ impl<T> EventLoop<T> {
     ///   (that Rust doesn't see) that will also mean that the rest of the function is never executed
     ///   and any values not passed to this function will *not* be dropped.
     ///
-    ///   Web applications are recommended to use `spawn()` instead of `run()` to avoid the need
+    ///   Web applications are recommended to use
+    #[cfg_attr(
+        wasm_platform,
+        doc = " [`spawn()`][crate::platform::web::EventLoopExtWebSys::spawn()] "
+    )]
+    #[cfg_attr(not(wasm_platform), doc = " `spawn()`[^1] ")]
+    /// instead of [`run()`] to avoid the need
     ///   for the Javascript exception trick, and to make it clearer that the event loop runs
     ///   asynchronously (via the browser's own, internal, event loop) and doesn't block the
     ///   current thread of execution like it does on other platforms.
     ///
     ///   This function won't be available with `target_feature = "exception-handling"`.
     ///
-    /// [`set_control_flow()`]: EventLoopWindowTarget::set_control_flow
+    #[cfg_attr(
+        not(wasm_platform),
+        doc = "[^1]: `spawn()` is only available on `wasm` platforms."
+    )]
+    ///
+    /// [`set_control_flow()`]: EventLoopWindowTarget::set_control_flow()
+    /// [`run()`]: Self::run()
     #[inline]
     #[cfg(not(all(wasm_platform, target_feature = "exception-handling")))]
     pub fn run<F>(self, event_handler: F) -> Result<(), EventLoopError>

src/lib.rs

@@ -22,20 +22,20 @@
 //! # Event handling
 //!
 //! Once a [`Window`] has been created, it will generate different *events*. A [`Window`] object can
-//! generate [`WindowEvent`]s when certain input events occur, such as a cursor moving over the
+//! generate [`Event::WindowEvent`]s when certain input events occur, such as a cursor moving over the
 //! window or a key getting pressed while the window is focused. Devices can generate
 //! [`DeviceEvent`]s, which contain unfiltered event data that isn't specific to a certain window.
-//! Some user activity, like mouse movement, can generate both a [`WindowEvent`] *and* a
+//! Some user activity, like mouse movement, can generate both a [`Event::WindowEvent`] *and* a
 //! [`DeviceEvent`]. You can also create and handle your own custom [`UserEvent`]s, if desired.
 //!
-//! You can retrieve events by calling [`EventLoop::run`][event_loop_run]. This function will
+//! You can retrieve events by calling [`EventLoop::run()`]. This function will
 //! dispatch events for every [`Window`] that was created with that particular [`EventLoop`], and
-//! will run until [`exit()`] is used, at which point [`Event`]`::`[`LoopExiting`].
+//! will run until [`exit()`] is used, at which point [`Event::LoopExiting`].
 //!
 //! Winit no longer uses a `EventLoop::poll_events() -> impl Iterator<Event>`-based event loop
 //! model, since that can't be implemented properly on some platforms (e.g web, iOS) and works poorly on
 //! most other platforms. However, this model can be re-implemented to an extent with
-//! [`EventLoopExtPumpEvents::pump_events`]. See that method's documentation for more reasons about why
+//! [`EventLoopExtPumpEvents::pump_events()`]. See that method's documentation for more reasons about why
 //! it's discouraged, beyond compatibility reasons.
 //!
 //!
@@ -92,7 +92,7 @@
 //! });
 //! ```
 //!
-//! [`Event`]`::`[`WindowEvent`] has a [`WindowId`] member. In multi-window environments, it should be
+//! [`Event::WindowEvent`] has a [`WindowId`] member. In multi-window environments, it should be
 //! compared to the value returned by [`Window::id()`][window_id_fn] to determine which [`Window`]
 //! dispatched the event.
 //!
@@ -110,9 +110,9 @@
 //! window visible only once you're ready to render into it.
 //!
 //! [`EventLoop`]: event_loop::EventLoop
-//! [`EventLoopExtPumpEvents::pump_events`]: ./platform/pump_events/trait.EventLoopExtPumpEvents.html#tymethod.pump_events
+//! [`EventLoopExtPumpEvents::pump_events()`]: ./platform/pump_events/trait.EventLoopExtPumpEvents.html#tymethod.pump_events
 //! [`EventLoop::new()`]: event_loop::EventLoop::new
-//! [event_loop_run]: event_loop::EventLoop::run
+//! [`EventLoop::run()`]: event_loop::EventLoop::run
 //! [`exit()`]: event_loop::EventLoopWindowTarget::exit
 //! [`Window`]: window::Window
 //! [`WindowId`]: window::WindowId
@@ -121,11 +121,10 @@
 //! [window_builder_new]: window::WindowBuilder::new
 //! [window_builder_build]: window::WindowBuilder::build
 //! [window_id_fn]: window::Window::id
-//! [`Event`]: event::Event
-//! [`WindowEvent`]: event::WindowEvent
+//! [`Event::WindowEvent`]: event::WindowEvent
 //! [`DeviceEvent`]: event::DeviceEvent
 //! [`UserEvent`]: event::Event::UserEvent
-//! [`LoopExiting`]: event::Event::LoopExiting
+//! [`Event::LoopExiting`]: event::Event::LoopExiting
 //! [`platform`]: platform
 //! [`raw_window_handle`]: ./window/struct.Window.html#method.raw_window_handle
 //! [`raw_display_handle`]: ./window/struct.Window.html#method.raw_display_handle

src/platform/run_on_demand.rs

@@ -37,7 +37,7 @@ pub trait EventLoopExtRunOnDemand {
     /// # Caveats
     /// - This extension isn't available on all platforms, since it's not always possible to
     ///   return to the caller (specifically this is impossible on iOS and Web - though with
-    ///   the Web backend it is possible to use `spawn()` more than once instead).
+    ///   the Web backend it is possible to use `spawn()`[^1] more than once instead).
     /// - No [`Window`] state can be carried between separate runs of the event loop.
     ///
     /// You are strongly encouraged to use [`EventLoop::run()`] for portability, unless you specifically need
@@ -57,8 +57,13 @@ pub trait EventLoopExtRunOnDemand {
     ///   on an event loop that is internal to the browser itself.
     /// - **iOS:** It's not possible to stop and start an `NSApplication` repeatedly on iOS.
     ///
-    /// [`exit()`]: EventLoopWindowTarget::exit
-    /// [`set_control_flow()`]: EventLoopWindowTarget::set_control_flow
+    #[cfg_attr(
+        not(wasm_platform),
+        doc = "[^1]: `spawn()` is only available on `wasm` platforms."
+    )]
+    ///
+    /// [`exit()`]: EventLoopWindowTarget::exit()
+    /// [`set_control_flow()`]: EventLoopWindowTarget::set_control_flow()
     fn run_on_demand<F>(&mut self, event_handler: F) -> Result<(), EventLoopError>
     where
         F: FnMut(Event<Self::UserEvent>, &EventLoopWindowTarget<Self::UserEvent>);