- * Implementations must call [`update_monitor`] with the given update. See
- * [`ChannelMonitorUpdateStatus`] for invariants around returning an error.
+ * Implementations must call [`ChannelMonitor::update_monitor`] with the given update. This
+ * may fail (returning an `Err(())`), in which case this should return
+ * [`ChannelMonitorUpdateStatus::InProgress`] (and the update should never complete). This
+ * generally implies the channel has been closed (either by the funding outpoint being spent
+ * on-chain or the [`ChannelMonitor`] having decided to do so and broadcasted a transaction),
+ * and the [`ChannelManager`] state will be updated once it sees the funding spend on-chain.
+ *
+ * In general, persistence failures should be retried after returning
+ * [`ChannelMonitorUpdateStatus::InProgress`] and eventually complete. If a failure truly
+ * cannot be retried, the node should shut down immediately after returning
+ * [`ChannelMonitorUpdateStatus::UnrecoverableError`], see its documentation for more info.