From: Matt Corallo <git@bluematt.me>
Date: Sat, 30 Oct 2021 01:52:43 +0000 (+0000)
Subject: Expand `InvoicePayer` documentation somewhat to clarify edge-cases
X-Git-Tag: v0.0.103~4^2~5
X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=51dd344f26ca31d114fd06608eef4f8e6b6f8b57;p=rust-lightning

Expand `InvoicePayer` documentation somewhat to clarify edge-cases
---

diff --git a/lightning-invoice/src/payment.rs b/lightning-invoice/src/payment.rs
index eefae3fc1..68b06faa0 100644
--- a/lightning-invoice/src/payment.rs
+++ b/lightning-invoice/src/payment.rs
@@ -175,6 +175,10 @@ pub trait Router<S: routing::Score> {
 }
 
 /// Number of attempts to retry payment path failures for an [`Invoice`].
+///
+/// Note that this is the number of *path* failures, not full payment retries. For multi-path
+/// payments, if this is less than the total number of paths, we will never even retry all of the
+/// payment's paths.
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub struct RetryAttempts(pub usize);
 
@@ -216,6 +220,10 @@ where
 	}
 
 	/// Pays the given [`Invoice`], caching it for later use in case a retry is needed.
+	///
+	/// You should ensure that the `invoice.payment_hash()` is unique and the same payment_hash has
+	/// never been paid before. Because [`InvoicePayer`] is stateless no effort is made to do so
+	/// for you.
 	pub fn pay_invoice(&self, invoice: &Invoice) -> Result<PaymentId, PaymentError> {
 		if invoice.amount_milli_satoshis().is_none() {
 			Err(PaymentError::Invoice("amount missing"))
@@ -226,6 +234,10 @@ where
 
 	/// Pays the given zero-value [`Invoice`] using the given amount, caching it for later use in
 	/// case a retry is needed.
+	///
+	/// You should ensure that the `invoice.payment_hash()` is unique and the same payment_hash has
+	/// never been paid before. Because [`InvoicePayer`] is stateless no effort is made to do so
+	/// for you.
 	pub fn pay_zero_value_invoice(
 		&self, invoice: &Invoice, amount_msats: u64
 	) -> Result<PaymentId, PaymentError> {