f rename and redo docs

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -523,30 +523,34 @@ impl BestBlock {
 }
 
 #[derive(Copy, Clone, PartialEq)]
-enum PersistenceGuardOption {
+enum NotifyOption {
 	DoPersist,
 	SkipPersist,
 }
 
 /// Whenever we release the `ChannelManager`'s `total_consistency_lock`, from read mode, it is
 /// desirable to notify any listeners on `await_persistable_update_timeout`/
-/// `await_persistable_update` that new updates are available for persistence. Therefore, this
+/// `await_persistable_update` when new updates are available for persistence. Therefore, this
 /// struct is responsible for locking the total consistency lock and, upon going out of scope,
 /// sending the aforementioned notification (since the lock being released indicates that the
 /// updates are ready for persistence).
-struct PersistenceNotifierGuard<'a, F: Fn() -> PersistenceGuardOption> {
+///
+/// We allow callers to either always notify by constructing with `notify_on_drop` or chose to
+/// notify or not based on whether relevant changes have been made, providing a closure to
+/// `optionally_notify` which returns a `NotifyOption`.
+struct PersistenceNotifierGuard<'a, F: Fn() -> NotifyOption> {
 	persistence_notifier: &'a PersistenceNotifier,
 	should_persist: F,
 	// We hold onto this result so the lock doesn't get released immediately.
 	_read_guard: RwLockReadGuard<'a, ()>,
 }
 
-impl<'a> PersistenceNotifierGuard<'a, fn() -> PersistenceGuardOption> { // We don't care what the concrete F is here, its unused
-	fn notify_on_drop(lock: &'a RwLock<()>, notifier: &'a PersistenceNotifier) -> PersistenceNotifierGuard<'a, impl Fn() -> PersistenceGuardOption> {
-		PersistenceNotifierGuard::optionally_notify(lock, notifier, || -> PersistenceGuardOption { PersistenceGuardOption::DoPersist })
+impl<'a> PersistenceNotifierGuard<'a, fn() -> NotifyOption> { // We don't care what the concrete F is here, its unused
+	fn notify_on_drop(lock: &'a RwLock<()>, notifier: &'a PersistenceNotifier) -> PersistenceNotifierGuard<'a, impl Fn() -> NotifyOption> {
+		PersistenceNotifierGuard::optionally_notify(lock, notifier, || -> NotifyOption { NotifyOption::DoPersist })
 	}
 
-	fn optionally_notify<F: Fn() -> PersistenceGuardOption>(lock: &'a RwLock<()>, notifier: &'a PersistenceNotifier, persist_check: F) -> PersistenceNotifierGuard<'a, F> {
+	fn optionally_notify<F: Fn() -> NotifyOption>(lock: &'a RwLock<()>, notifier: &'a PersistenceNotifier, persist_check: F) -> PersistenceNotifierGuard<'a, F> {
 		let read_guard = lock.read().unwrap();
 
 		PersistenceNotifierGuard {
@@ -557,9 +561,9 @@ impl<'a> PersistenceNotifierGuard<'a, fn() -> PersistenceGuardOption> { // We do
 	}
 }
 
-impl<'a, F: Fn() -> PersistenceGuardOption> Drop for PersistenceNotifierGuard<'a, F> {
+impl<'a, F: Fn() -> NotifyOption> Drop for PersistenceNotifierGuard<'a, F> {
 	fn drop(&mut self) {
-		if (self.should_persist)() == PersistenceGuardOption::DoPersist {
+		if (self.should_persist)() == NotifyOption::DoPersist {
 			self.persistence_notifier.notify();
 		}
 	}
@@ -2141,8 +2145,8 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 	/// Note that in some rare cases this may generate a `chain::Watch::update_channel` call.
 	pub fn timer_tick_occurred(&self) {
 		PersistenceNotifierGuard::optionally_notify(&self.total_consistency_lock, &self.persistence_notifier, || {
-			let mut should_persist = PersistenceGuardOption::SkipPersist;
-			if self.process_background_events() { should_persist = PersistenceGuardOption::DoPersist; }
+			let mut should_persist = NotifyOption::SkipPersist;
+			if self.process_background_events() { should_persist = NotifyOption::DoPersist; }
 
 			let mut channel_state_lock = self.channel_state.lock().unwrap();
 			let channel_state = &mut *channel_state_lock;
@@ -2158,7 +2162,7 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 								msg: update
 							});
 						}
-						should_persist = PersistenceGuardOption::DoPersist;
+						should_persist = NotifyOption::DoPersist;
 						chan.set_update_status(UpdateStatus::Disabled);
 					},
 					UpdateStatus::EnabledStaged if chan.is_live() => {
@@ -2167,7 +2171,7 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 								msg: update
 							});
 						}
-						should_persist = PersistenceGuardOption::DoPersist;
+						should_persist = NotifyOption::DoPersist;
 						chan.set_update_status(UpdateStatus::Enabled);
 					},
 					_ => {},