Update docs regarding payment paths

Author: jkczyz

lightning/src/offers/invoice.rs

@@ -339,7 +339,8 @@ struct InvoiceFields {
 impl Invoice {
 	/// Paths to the recipient originating from publicly reachable nodes, including information
 	/// needed for routing payments across them. Blinded paths provide recipient privacy by
-	/// obfuscating its node id.
+	/// obfuscating its node id and may serve as hints to find a successful payment path to the
+	/// recipient.
 	pub fn payment_paths(&self) -> &[(BlindedPath, BlindedPayInfo)] {
 		&self.contents.fields().payment_paths[..]
 	}

lightning/src/offers/invoice_request.rs

@@ -333,7 +333,8 @@ impl InvoiceRequest {
 	/// for the invoice.
 	///
 	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
-	/// must contain one or more elements.
+	/// must contain one or more elements ordered from most-preferred to least-preferred, if there's
+	/// a preference.
 	///
 	/// Errors if the request contains unknown required features.
 	///

lightning/src/offers/refund.rs

@@ -331,7 +331,8 @@ impl Refund {
 	/// offer, which does have a `signing_pubkey`.
 	///
 	/// The `payment_paths` parameter is useful for maintaining the payment recipient's privacy. It
-	/// must contain one or more elements.
+	/// must contain one or more elements ordered from most-preferred to least-preferred, if there's
+	/// a preference.
 	///
 	/// Errors if the request contains unknown required features.
 	///