Update docs regarding payment path privacy

Author: jkczyz

lightning/src/offers/invoice.rs

@@ -338,8 +338,10 @@ 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.
+	/// needed for routing payments across them.
+	///
+	/// Blinded paths provide recipient privacy by obfuscating its node id. Note, however, that this
+	/// privacy is lost if a public node id is used for [`Invoice::signing_pubkey`].
 	pub fn payment_paths(&self) -> &[(BlindedPath, BlindedPayInfo)] {
 		&self.contents.fields().payment_paths[..]
 	}

lightning/src/offers/invoice_request.rs

@@ -333,7 +333,9 @@ 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. Note, however, that any privacy is lost if a public node id was used for
+	/// [`Offer::signing_pubkey`].
 	///
 	/// Errors if the request contains unknown required features.
 	///

lightning/src/offers/refund.rs

@@ -331,7 +331,9 @@ 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. Note, however, that any privacy is lost if a public node id is used for
+	/// `signing_pubkey`.
 	///
 	/// Errors if the request contains unknown required features.
 	///