f - Fix docs

Author: jkczyz

lightning-invoice/src/payment.rs

@@ -16,19 +16,18 @@
 //!
 //! [`InvoicePayer`] caches each [`Invoice`] by its `payment_hash` so that it can retry the payment
 //! if it fails. It accomplishes this by implementing [`EventHandler`] which decorates a
-//! user-provided handler. It will intercepts any [`Event::PaymentPathFailed`] events and retry the
-//! payment a fixed number of times before failing or succeeding as needed.
+//! user-provided handler. It will intercept any [`Event::PaymentPathFailed`] events and retry the
+//! payment a fixed number of times before failing or succeeding as appropriate.
 //!
 //! # Example
 //!
 //! TODO: Fill this in once the API is finalized.
 //!
 //! # Note
 //!
-//! The [`Route`] is compute before each payment attempt. Any updates affecting path finding such as
-//! updates to the network graph or changes to channels scores should be applied prior to retries.
-//! This typically means any [`EventHandler`] decorators responsible for this should decorate
-//! [`InvoicePayer`] so that such changes take effect before retrying.
+//! The [`Route`] is computed before each payment attempt. Any updates affecting path finding such
+//! as updates to the network graph or changes to channel scores should be applied prior to
+//! retries, typically by way of composing [`EventHandler`]s accordingly.
 
 use crate::Invoice;
 
@@ -112,7 +111,11 @@ where
 	L::Target: Logger,
 	E: EventHandler,
 {
-	/// Creates an invoice payer.
+	/// Creates an invoice payer that does not retry.
+	///
+	/// To enable retries, chain `new` with a call to [`with_retry_attempts`].
+	///
+	/// [`with_retry_attempts`]: Self::with_retry_attempts
 	pub fn new(payer: P, router: R, logger: L, event_handler: E) -> Self {
 		Self {
 			payer,
@@ -130,7 +133,7 @@ where
 		Self { retry_attempts, ..self }
 	}
 
-	/// Pays the given [`Invoice`], caching it for later use if a retry is needed.
+	/// Pays the given [`Invoice`], caching it for later use in case a retry is needed.
 	pub fn pay_invoice(&self, invoice: &Invoice) -> Result<(), PaymentError> {
 		let payment_hash = PaymentHash(invoice.payment_hash().clone().into_inner());
 		let mut invoice_cache = self.invoice_cache.lock().unwrap();