f write real docs

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -3230,7 +3230,11 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 		}
 	}
 
-	/// Process pending events from the `chain::Watch`.
+	/// Check the holding cell in each channel and free any pending HTLCs in them if possible.
+	/// This should only apply to HTLCs which were added to the holding cell because we were
+	/// waiting on a monitor update to finish. In that case, we don't want to free the holding cell
+	/// directly in `channel_monitor_updated` as it may introduce deadlocks calling back into user
+	/// code to inform them of a channel monitor update.
 	fn check_free_holding_cells(&self) {
 		let mut forwarding_failed_htlcs = Vec::new();
 		let mut handle_errors = Vec::new();