f rewrite function docs as suggested

lightning/src/ln/channel.rs

@@ -3974,14 +3974,18 @@ impl<Signer: Sign> Channel<Signer> {
 
 	/// Adds a pending outbound HTLC to this channel, note that you probably want
 	/// send_htlc_and_commit instead cause you'll want both messages at once.
-	/// This returns an option instead of a pure UpdateAddHTLC as we may be in a state where we
-	/// cannot add HTLCs on the wire.
-	/// In cases where we're waiting on the remote peer to send us a revoke_and_ack, if we did, we
-	/// wouldn't be able to determine what they actually ACK'ed when we do receive the
-	/// revoke_and_ack.
-	/// In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we may
-	/// not yet have sent the previous commitment update messages and will need to regenerate them.
-	/// You MUST call send_commitment prior to any other calls on this Channel
+	///
+	/// This returns an optional UpdateAddHTLC as we may be in a state where we cannot add HTLCs on
+	/// the wire:
+	/// * In cases where we're waiting on the remote peer to send us a revoke_and_ack, we
+	///   wouldn't be able to determine what they actually ACK'ed if we have two sets of updates
+	///   awaiting ACK.
+	/// * In cases where we're marked MonitorUpdateFailed, we cannot commit to a new state as we
+	///   may not yet have sent the previous commitment update messages and will need to regenerate
+	///   them.
+	///
+	/// You MUST call send_commitment prior to calling any other methods on this Channel!
+	///
 	/// If an Err is returned, it's a ChannelError::Ignore!
 	pub fn send_htlc(&mut self, amount_msat: u64, payment_hash: PaymentHash, cltv_expiry: u32, source: HTLCSource, onion_routing_packet: msgs::OnionPacket) -> Result<Option<msgs::UpdateAddHTLC>, ChannelError> {
 		if (self.channel_state & (ChannelState::ChannelFunded as u32 | BOTH_SIDES_SHUTDOWN_MASK)) != (ChannelState::ChannelFunded as u32) {