f add guidance for setting max pending updates

Author: domZippilli

lightning/src/util/persist.rs

@@ -377,8 +377,18 @@ where
 	///
 	/// The `maximum_pending_updates` parameter controls how many updates may be stored before a
 	/// [`MonitorUpdatingPersister`] consolidates updates by writing a full monitor. Note that
-	/// consolidation will frequently occur with fewer updates, this number is merely the maximum
-	/// that may be stored.
+	/// consolidation will frequently occur with fewer updates than what you set here; this number
+	/// is merely the maximum that may be stored. When setting this value, consider that for higher
+	/// values of `maximum_pending_updates`:
+	/// 
+	///   - [`MonitorUpdatingPersister`] will tend to write more [`ChannelMonitorUpdate`]s than
+	/// [`ChannelMonitor`]s, approaching one [`ChannelMonitor`] write for every
+	/// `maximum_pending_updates` [`ChannelMonitorUpdate`]s.
+	///   - [`MonitorUpdatingPersister`] will issue deletes differently. Lazy deletes will come in
+	/// "waves" for each [`ChannelMonitor`] write. A larger `maximum_pending_updates` means bigger,
+	/// less frequent "waves."
+	///   - [`MonitorUpdatingPersister`] will potentially have more listing to do if you need to run
+	/// [`MonitorUpdatingPersister::cleanup_stale_updates`].
 	pub fn new(
 		kv_store: K, logger: L, maximum_pending_updates: u64, entropy_source: ES,
 		signer_provider: SP,