f write docs

Author: TheBlueMatt

lightning/src/ln/channel.rs

@@ -3678,6 +3678,8 @@ impl<Signer: Sign> Channel<Signer> {
 		Ok((None, timed_out_htlcs))
 	}
 
+	/// Indicates the funding transaction is no longer confirmed in the main chain. This may
+	/// force-close the channel, but may also indicate a harmless reorganization of a block or two.
 	pub fn funding_transaction_unconfirmed(&mut self) -> Result<(), msgs::ErrorMessage> {
 		if self.funding_tx_confirmation_height != 0 {
 			let effective_new_height = self.funding_tx_confirmation_height - 1;

lightning/src/ln/channelmanager.rs

@@ -3524,7 +3524,13 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 		}
 	}
 
-	/// Gets the set of txids which should be monitored for their confirmation state. XXX: Docs
+	/// Gets the set of txids which should be monitored for their confirmation state.
+	///
+	/// If you're providing information about reorganizations via [`transaction_unconfirmed`], this
+	/// is the set of transactions which you may been to call [`transaction_unconfirmed`] for.
+	///
+	/// Note that this is NOT the set of transactions which must be included in calls to
+	/// [`transactions_confirmed`] if they are confirmed, but a small subset of it.
 	pub fn get_relevant_txids(&self) -> Vec<Txid> {
 		let channel_state = self.channel_state.lock().unwrap();
 		let mut res = Vec::with_capacity(channel_state.short_to_id.len());
@@ -3536,7 +3542,19 @@ impl<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref> ChannelMana
 		res
 	}
 
-	/// Marks a transaction as having been reorganized out of the blockchain XXX: Docs
+	/// Marks a transaction as having been reorganized out of the blockchain.
+	///
+	/// If a transaction is included in [`get_relevant_txids`], and is no longer in the main branch
+	/// of the blockchain, this function should be called to indicate that the transaction should
+	/// be considered reorganized out.
+	///
+	/// Once this is called, the given transaction will no longer appear on [`get_relevant_txids`],
+	/// though this may be called repeatedly for a given transaction without issue.
+	///
+	/// Note that if the transaction is confirmed on the main chain in a different block (indicated
+	/// via a call to [`transactions_confirmed`]), it may re-appear in [`get_relevant_txids`], thus
+	/// be very weary of race-conditions wherein the final state of a transaction indicated via
+	/// these APIs is not the same as its state on the blockchain.
 	pub fn transaction_unconfirmed(&self, txid: &Txid) {
 		let _persistence_guard = PersistenceNotifierGuard::new(&self.total_consistency_lock, &self.persistence_notifier);
 		self.do_chain_event(None, |channel| {