From 2751dafe867abbeef9139584fa45ab7d2ae9ace3 Mon Sep 17 00:00:00 2001
From: Daniel McNab <36049421+DJMcNab@users.noreply.github.com>
Date: Sat, 26 Aug 2023 17:45:15 +0100
Subject: [PATCH] Update documentation to reflect changes

---
 CHANGELOG.md       |  6 ++++++
 src/sources/mod.rs | 15 +++++++++++----
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9ba48fc0..df5fcad4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+#### Breaking changes
+
+- `pre_run` and `post_run` on `EventSource` have been replaced with `before_will_sleep` and `before_handle_events`, respectively.
+  These are now opt-in through the `NEEDS_EXTRA_LIFECYCLE_EVENTS` associated constant, and occur at slightly different times to
+  the methods they are replacing. This allows greater compatibility with Wayland based event sources.
+
 ## 0.11.0 -- 2023-06-05
 
 #### Bugfixes
diff --git a/src/sources/mod.rs b/src/sources/mod.rs
index 3827a8fb..68e72c1c 100644
--- a/src/sources/mod.rs
+++ b/src/sources/mod.rs
@@ -85,10 +85,17 @@ impl BitOrAssign for PostAction {
 ///
 /// In case your event source needs to do some special processing before or after a
 /// polling session occurs (to prepare the underlying source for polling, and cleanup
-/// after that), you can override the `pre_run` and `post_run`, that do nothing by
-/// default. Depending on the underlying events, `process_events` may be invoked once,
-/// several times, or none at all between `pre_run` and `post_run` are called, but when
-/// it is invoked, it'll always be between those two.
+/// after that), you can override [`NEEDS_EXTRA_LIFECYCLE_EVENTS`] to `true`.
+/// For all sources for which that constant is `true`, the methods [`before_will_sleep`] and
+/// [`before_handle_events`] will be called.
+/// [`before_will_sleep`] is called before the polling system performs a poll operation.
+/// [`before_handle_events`] is called before any process_events methods have been called.
+/// This means that during `process_events` you can assume that all cleanup has occured on
+/// all sources.
+///
+/// [`NEEDS_EXTRA_LIFECYCLE_EVENTS`]: EventSource::NEEDS_EXTRA_LIFECYCLE_EVENTS
+/// [`before_will_sleep`]: EventSource::before_will_sleep
+/// [`before_handle_events`]: EventSource::before_handle_events
 pub trait EventSource {
     /// The type of events generated by your source.
     type Event;