From 276597e0093fab1486c0a83720da883b6020a2f8 Mon Sep 17 00:00:00 2001
From: Kirill Chibisov <contact@kchibisov.com>
Date: Sat, 3 May 2025 21:04:27 +0900
Subject: [PATCH] winit-core: cleanup event loop docs

---
 winit-core/src/application/mod.rs | 14 +-------------
 winit-core/src/event_loop.rs      | 12 +++++++-----
 2 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/winit-core/src/application/mod.rs b/winit-core/src/application/mod.rs
index b579cb40..b9fd34bf 100644
--- a/winit-core/src/application/mod.rs
+++ b/winit-core/src/application/mod.rs
@@ -7,16 +7,6 @@ use crate::window::WindowId;
 pub mod macos;
 
 /// The handler of application-level events.
-///
-/// See [the top-level docs] for example usage, and [`EventLoop::run_app`] for an overview of when
-/// events are delivered.
-///
-/// This is [dropped] when the event loop is shut down. Note that this only works if you're passing
-/// the entire state to [`EventLoop::run_app`] (passing `&mut app` won't work).
-///
-/// [the top-level docs]: crate
-/// [`EventLoop::run_app`]: crate::event_loop::EventLoop::run_app
-/// [dropped]: std::ops::Drop
 pub trait ApplicationHandler {
     /// Emitted when new events arrive from the OS to be processed.
     ///
@@ -211,9 +201,7 @@ pub trait ApplicationHandler {
 
     /// Emitted when the OS sends an event to a device.
     ///
-    /// For this to be called, it must be enabled with [`EventLoop::listen_device_events`].
-    ///
-    /// [`EventLoop::listen_device_events`]: crate::event_loop::EventLoop::listen_device_events
+    /// Whether device events are delivered depends on the backend in use.
     fn device_event(
         &mut self,
         event_loop: &dyn ActiveEventLoop,
diff --git a/winit-core/src/event_loop.rs b/winit-core/src/event_loop.rs
index 0a68d020..c1ad81ca 100644
--- a/winit-core/src/event_loop.rs
+++ b/winit-core/src/event_loop.rs
@@ -109,7 +109,7 @@ pub trait ActiveEventLoop: AsAny + fmt::Debug {
     /// [qa1561]: https://developer.apple.com/library/archive/qa/qa1561/_index.html
     fn exit(&self);
 
-    /// Returns whether the [`EventLoop`] is about to stop.
+    /// Returns whether the [`ActiveEventLoop`] is about to stop.
     ///
     /// Set by [`exit()`][Self::exit].
     fn exiting(&self) -> bool;
@@ -131,14 +131,15 @@ impl HasDisplayHandle for dyn ActiveEventLoop + '_ {
 
 impl_dyn_casting!(ActiveEventLoop);
 
-/// Control the [`EventLoop`], possibly from a different thread, without referencing it directly.
+/// Control the [`ActiveEventLoop`], possibly from a different thread, without referencing it
+/// directly.
 #[derive(Clone, Debug)]
 pub struct EventLoopProxy {
     pub(crate) proxy: Arc<dyn EventLoopProxyProvider>,
 }
 
 impl EventLoopProxy {
-    /// Wake up the [`EventLoop`], resulting in [`ApplicationHandler::proxy_wake_up()`] being
+    /// Wake up the [`ActiveEventLoop`], resulting in [`ApplicationHandler::proxy_wake_up()`] being
     /// called.
     ///
     /// Calls to this method are coalesced into a single call to [`proxy_wake_up`], see the
@@ -146,7 +147,8 @@ impl EventLoopProxy {
     ///
     /// If the event loop is no longer running, this is a no-op.
     ///
-    /// [`proxy_wake_up`]: ApplicationHandler::proxy_wake_up
+    /// [`proxy_wake_up`]: crate::application::ApplicationHandler::proxy_wake_up
+    /// [`ApplicationHandler::proxy_wake_up()`]: crate::application::ApplicationHandler::proxy_wake_up
     ///
     /// # Platform-specific
     ///
@@ -171,7 +173,7 @@ pub trait EventLoopProxyProvider: Send + Sync + Debug {
 ///
 /// The purpose of this type is to provide a cheaply cloneable handle to the underlying
 /// display handle. This is often used by graphics APIs to connect to the underlying APIs.
-/// It is difficult to keep a handle to the [`EventLoop`] type or the [`ActiveEventLoop`]
+/// It is difficult to keep a handle to the underlying event loop type or the [`ActiveEventLoop`]
 /// type. In contrast, this type involves no lifetimes and can be persisted for as long as
 /// needed.
 ///