f Update docs and comment with Val's feedback

Author: TheBlueMatt

lightning/src/ln/channelmanager.rs

@@ -1204,7 +1204,8 @@ impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref> ChannelMan
 	/// May generate SendHTLCs message(s) event on success, which should be relayed.
 	///
 	/// Each path may have a different return value, and PaymentSendValue may return a Vec with
-	/// each entry matching the corresponding-index entry in the route paths.
+	/// each entry matching the corresponding-index entry in the route paths, see
+	/// PaymentSendFailure for more info.
 	///
 	/// In general, a path may raise:
 	///  * APIError::RouteError when an invalid route or forwarding parameter (cltv_delta, fee,
@@ -1298,9 +1299,10 @@ impl<ChanSigner: ChannelKeys, M: Deref, T: Deref, K: Deref, F: Deref> ChannelMan
 							if let Err(e) = self.monitor.update_monitor(chan.get().get_funding_txo().unwrap(), monitor_update) {
 								maybe_break_monitor_err!(self, e, channel_state, chan, RAACommitmentOrder::CommitmentFirst, false, true);
 								// Note that MonitorUpdateFailed here indicates (per function docs)
-								// that we will resent the commitment update once we unfree monitor
-								// updating, so we have to take special care that we don't return
-								// something else in case we will resend later!
+								// that we will resend the commitment update once monitor updating
+								// is restored. Therefore, we must return an error indicating that
+								// it is unsafe to retry the payment wholesale, which we do in the
+								// next check for MonitorUpdateFailed, below.
 								check_res_push!(Err(APIError::MonitorUpdateFailed));
 							}