Re-write Offer::issuer_signing_pubkey documentation

diff --git a/lightning/src/offers/offer.rs b/lightning/src/offers/offer.rs
index 2a1a68575287c747c9accb875166aec886ac3c7a..37cb5df7e87c288da37697734bb80253aa8b5f9a 100644 (file)
--- a/lightning/src/offers/offer.rs
+++ b/lightning/src/offers/offer.rs
@@ -631,7 +631,17 @@ macro_rules! offer_accessors { ($self: ident, $contents: expr) => {
                $contents.supported_quantity()
        }
 
-       /// The public key used by the recipient to sign invoices.
+       /// The public key corresponding to the key used by the recipient to sign invoices.
+       /// - If [`Offer::paths`] is empty, MUST be `Some` and contain the recipient's node id for
+       ///   sending an [`InvoiceRequest`].
+       /// - If [`Offer::paths`] is not empty, MAY be `Some` and contain a transient id.
+       /// - If `None`, the signing pubkey will be the final blinded node id from the
+       ///   [`BlindedMessagePath`] in [`Offer::paths`] used to send the [`InvoiceRequest`].
+       ///
+       /// See also [`Bolt12Invoice::signing_pubkey`].
+       ///
+       /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+       /// [`Bolt12Invoice::signing_pubkey`]: crate::offers::invoice::Bolt12Invoice::signing_pubkey
        pub fn issuer_signing_pubkey(&$self) -> Option<bitcoin::secp256k1::PublicKey> {
                $contents.issuer_signing_pubkey()
        }