f - expand InvoiceRequestBuilder::metadata docs

Author: jkczyz

lightning/src/offers/invoice_request.rs

@@ -91,9 +91,13 @@ impl<'a> InvoiceRequestBuilder<'a> {
 		}
 	}
 
-	/// Sets the metadata for the invoice request. Useful for containing information about the
-	/// derivation of [`InvoiceRequest::payer_id`]. This should not leak any information such as
-	/// using a simple BIP-32 derivation path.
+	/// Sets the metadata for the invoice request, which will be reflected in the invoice response.
+	/// Useful for including information about the derivation of [`InvoiceRequest::payer_id`] such
+	/// that invoice response handling can be stateless. Also serves as payer-provided entropy while
+	/// hashing in the signature calculation.
+	///
+	/// This should not leak any information such as by using a simple BIP-32 derivation path.
+	/// Otherwise, payments may be correlated.
 	///
 	/// Successive calls to this method will override the previous setting.
 	pub fn metadata(mut self, metadata: Vec<u8>) -> Self {