f Fix non-std docs for lightning

Author: tnull

lightning/src/events/mod.rs

@@ -543,12 +543,13 @@ pub enum PaymentFailureReason {
 	///
 	/// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
 	UserAbandoned,
-	/// We exhausted all of our retry attempts while trying to send the payment, or we
-	/// exhausted the [`Retry::Timeout`] if the user set one. If at any point a retry
-	/// attempt failed while being forwarded along the path, an [`Event::PaymentPathFailed`] will
+	#[cfg_attr(feature = "std", doc = "We exhausted all of our retry attempts while trying to send the payment, or we")]
+	#[cfg_attr(feature = "std", doc = "exhausted the [`Retry::Timeout`] if the user set one.")]
+	#[cfg_attr(not(feature = "std"), doc = "We exhausted all of our retry attempts while trying to send the payment.")]
+	/// If at any point a retry attempt failed while being forwarded along the path, an [`Event::PaymentPathFailed`] will
 	/// have come before this.
-	///
-	/// [`Retry::Timeout`]: crate::ln::channelmanager::Retry::Timeout
+	#[cfg_attr(feature = "std", doc = "")]
+	#[cfg_attr(feature = "std", doc = "[`Retry::Timeout`]: crate::ln::channelmanager::Retry::Timeout")]
 	RetriesExhausted,
 	/// The payment expired while retrying, based on the provided
 	/// [`PaymentParameters::expiry_time`].

lightning/src/ln/invoice_utils.rs

@@ -61,9 +61,8 @@ use core::iter::Iterator;
 /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
 /// [`PhantomRouteHints::channels`]: crate::ln::channelmanager::PhantomRouteHints::channels
 /// [`MIN_FINAL_CLTV_EXPIRY_DETLA`]: crate::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
-///
-/// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
-/// available and the current time is supplied by the caller.
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not available and the current time is supplied by the caller.")]
 pub fn create_phantom_invoice<ES: Deref, NS: Deref, L: Deref>(
 	amt_msat: Option<u64>, payment_hash: Option<PaymentHash>, description: String,
 	invoice_expiry_delta_secs: u32, phantom_route_hints: Vec<PhantomRouteHints>, entropy_source: ES,
@@ -117,9 +116,8 @@ where
 /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
 /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
 /// [`PhantomRouteHints::channels`]: crate::ln::channelmanager::PhantomRouteHints::channels
-///
-/// This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
-/// available and the current time is supplied by the caller.
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not available and the current time is supplied by the caller.")]
 pub fn create_phantom_invoice_with_description_hash<ES: Deref, NS: Deref, L: Deref>(
 	amt_msat: Option<u64>, payment_hash: Option<PaymentHash>, invoice_expiry_delta_secs: u32,
 	description_hash: Sha256, phantom_route_hints: Vec<PhantomRouteHints>, entropy_source: ES,
@@ -399,9 +397,12 @@ where
 	)
 }
 
-/// See [`create_invoice_from_channelmanager_with_description_hash`]
-/// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
-/// available and the current time is supplied by the caller.
+/// Utility to construct an invoice. Generally, unless you want to do something like a custom
+/// `cltv_expiry`, this is what you should be using to create an invoice.
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "See [`create_invoice_from_channelmanager_with_description_hash`] for more information.")]
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "This can be used in a `no_std` environment, where [`std::time::SystemTime`] is not available and the current time is supplied by the caller.")]
 pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>, node_signer: NS, logger: L,
 	network: Currency, amt_msat: Option<u64>, description_hash: Sha256,
@@ -424,9 +425,12 @@ pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_sin
 	)
 }
 
-/// See [`create_invoice_from_channelmanager`]
-/// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
-/// available and the current time is supplied by the caller.
+/// Utility to construct an invoice. Generally, unless you want to do something like a custom
+/// `cltv_expiry`, this is what you should be using to create an invoice.
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "See [`create_invoice_from_channelmanager`] for more information.")]
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not available and the current time is supplied by the caller.")]
 pub fn create_invoice_from_channelmanager_and_duration_since_epoch<M: Deref, T: Deref, ES: Deref, NS: Deref, SP: Deref, F: Deref, R: Deref, L: Deref>(
 	channelmanager: &ChannelManager<M, T, ES, NS, SP, F, R, L>, node_signer: NS, logger: L,
 	network: Currency, amt_msat: Option<u64>, description: String, duration_since_epoch: Duration,

lightning/src/ln/msgs.rs

@@ -87,7 +87,7 @@ pub enum DecodeError {
 	ShortRead,
 	/// A length descriptor in the packet didn't describe the later data correctly.
 	BadLengthDescriptor,
-	/// Error from [`std::io`].
+	/// Error from [`crate::io`].
 	Io(io::ErrorKind),
 	/// The message included zlib-compressed values, which we don't support.
 	UnsupportedCompression,

lightning/src/ln/outbound_payment.rs

@@ -438,8 +438,9 @@ impl_writeable_tlv_based_enum_legacy!(StaleExpiration,
 /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum RetryableSendFailure {
-	/// The provided [`PaymentParameters::expiry_time`] indicated that the payment has expired. Note
-	/// that this error is *not* caused by [`Retry::Timeout`].
+	/// The provided [`PaymentParameters::expiry_time`] indicated that the payment has expired.
+	#[cfg_attr(feature = "std", doc = "")]
+	#[cfg_attr(feature = "std", doc = "Note that this error is *not* caused by [`Retry::Timeout`].")]
 	///
 	/// [`PaymentParameters::expiry_time`]: crate::routing::router::PaymentParameters::expiry_time
 	PaymentExpired,

lightning/src/offers/invoice_macros.rs

@@ -16,7 +16,7 @@ macro_rules! invoice_builder_methods_common { (
 	#[doc = concat!("Sets the [`", stringify!($invoice_type), "::relative_expiry`]")]
 	#[doc = concat!("as seconds since [`", stringify!($invoice_type), "::created_at`].")]
 	#[doc = "Any expiry that has already passed is valid and can be checked for using"]
-	#[doc = concat!("[`", stringify!($invoice_type), "::is_expired`].")]
+	#[cfg_attr(feature = "std", doc = concat!("[`", stringify!($invoice_type), "::is_expired`]."))]
 	///
 	/// Successive calls to this method will override the previous setting.
 	pub fn relative_expiry($($self_mut)* $self: $self_type, relative_expiry_secs: u32) -> $return_type {

lightning/src/offers/invoice_request.rs

@@ -615,12 +615,11 @@ pub struct VerifiedInvoiceRequest {
 
 	/// Keys used for signing a [`Bolt12Invoice`] if they can be derived.
 	///
-	/// If `Some`, must call [`respond_using_derived_keys`] when responding. Otherwise, call
-	/// [`respond_with`].
-	///
+	#[cfg_attr(feature = "std", doc = "If `Some`, must call [`respond_using_derived_keys`] when responding. Otherwise, call [`respond_with`].")]
+	#[cfg_attr(feature = "std", doc = "")]
 	/// [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
-	/// [`respond_using_derived_keys`]: Self::respond_using_derived_keys
-	/// [`respond_with`]: Self::respond_with
+	#[cfg_attr(feature = "std", doc = "[`respond_using_derived_keys`]: Self::respond_using_derived_keys")]
+	#[cfg_attr(feature = "std", doc = "[`respond_with`]: Self::respond_with")]
 	pub keys: Option<Keypair>,
 }
 
@@ -719,8 +718,8 @@ macro_rules! invoice_request_respond_with_explicit_signing_pubkey_methods { (
 	/// Creates an [`InvoiceBuilder`] for the request with the given required fields.
 	///
 	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
-	/// `created_at`, which is used to set [`Bolt12Invoice::created_at`]. Useful for non-`std` builds
-	/// where [`std::time::SystemTime`] is not available.
+	/// `created_at`, which is used to set [`Bolt12Invoice::created_at`].
+	#[cfg_attr(feature = "std", doc = "Useful for non-`std` builds where [`std::time::SystemTime`] is not available.")]
 	///
 	/// The caller is expected to remember the preimage of `payment_hash` in order to claim a payment
 	/// for the invoice.

lightning/src/offers/offer.rs

@@ -316,8 +316,8 @@ macro_rules! offer_builder_methods { (
 		$return_value
 	}
 
-	/// Sets the [`Offer::absolute_expiry`] as seconds since the Unix epoch. Any expiry that has
-	/// already passed is valid and can be checked for using [`Offer::is_expired`].
+	/// Sets the [`Offer::absolute_expiry`] as seconds since the Unix epoch.
+	#[cfg_attr(feature = "std", doc = "Any expiry that has already passed is valid and can be checked for using [`Offer::is_expired`].")]
 	///
 	/// Successive calls to this method will override the previous setting.
 	pub fn absolute_expiry($($self_mut)* $self: $self_type, absolute_expiry: Duration) -> $return_type {

lightning/src/offers/parse.rs

@@ -135,7 +135,7 @@ pub enum Bolt12ParseError {
 /// Error when interpreting a TLV stream as a specific type.
 #[derive(Clone, Debug, PartialEq)]
 pub enum Bolt12SemanticError {
-	/// The current [`std::time::SystemTime`] is past the offer or invoice's expiration.
+	/// The current system time is past the offer or invoice's expiration.
 	AlreadyExpired,
 	/// The provided chain hash does not correspond to a supported chain.
 	UnsupportedChain,

lightning/src/offers/refund.rs

@@ -231,8 +231,8 @@ macro_rules! refund_builder_methods { (
 		$return_value
 	}
 
-	/// Sets the [`Refund::absolute_expiry`] as seconds since the Unix epoch. Any expiry that has
-	/// already passed is valid and can be checked for using [`Refund::is_expired`].
+	/// Sets the [`Refund::absolute_expiry`] as seconds since the Unix epoch.
+	#[cfg_attr(feature = "std", doc = "Any expiry that has already passed is valid and can be checked for using [`Refund::is_expired`].")]
 	///
 	/// Successive calls to this method will override the previous setting.
 	pub fn absolute_expiry($($self_mut)* $self: $self_type, absolute_expiry: Duration) -> $return_type {
@@ -545,8 +545,8 @@ macro_rules! respond_with_explicit_signing_pubkey_methods { ($self: ident, $buil
 	/// Creates an [`InvoiceBuilder`] for the refund with the given required fields.
 	///
 	/// Unless [`InvoiceBuilder::relative_expiry`] is set, the invoice will expire two hours after
-	/// `created_at`, which is used to set [`Bolt12Invoice::created_at`]. Useful for non-`std` builds
-	/// where [`std::time::SystemTime`] is not available.
+	/// `created_at`, which is used to set [`Bolt12Invoice::created_at`].
+	#[cfg_attr(feature = "std", doc = "Useful for non-`std` builds where [`std::time::SystemTime`] is not available.")]
 	///
 	/// The caller is expected to remember the preimage of `payment_hash` in order to
 	/// claim a payment for the invoice.

lightning/src/routing/gossip.rs

@@ -2121,9 +2121,9 @@ impl<L: Deref> NetworkGraph<L> where L::Target: Logger {
 	///
 	/// This method will also cause us to stop tracking removed nodes and channels if they have been
 	/// in the map for a while so that these can be resynced from gossip in the future.
-	///
-	/// This function takes the current unix time as an argument. For users with the `std` feature
-	/// enabled, [`NetworkGraph::remove_stale_channels_and_tracking`] may be preferable.
+	#[cfg_attr(feature = "std", doc = "")]
+	#[cfg_attr(feature = "std", doc = "This function takes the current unix time as an argument. For users with the `std` feature")]
+	#[cfg_attr(feature = "std", doc = "enabled, [`NetworkGraph::remove_stale_channels_and_tracking`] may be preferable.")]
 	pub fn remove_stale_channels_and_tracking_with_time(&self, current_time_unix: u64) {
 		let mut channels = self.channels.write().unwrap();
 		// Time out if we haven't received an update in at least 14 days.

lightning/src/util/ser.rs

@@ -50,8 +50,8 @@ use crate::util::string::UntrustedString;
 /// serialization buffer size
 pub const MAX_BUF_SIZE: usize = 64 * 1024;
 
-/// A simplified version of [`std::io::Write`] that exists largely for backwards compatibility.
-/// An impl is provided for any type that also impls [`std::io::Write`].
+/// A simplified version of `std::io::Write` that exists largely for backwards compatibility.
+/// An impl is provided for any type that also impls `std::io::Write`.
 ///
 /// This is not exported to bindings users as we only export serialization to/from byte arrays instead
 pub trait Writer {
@@ -173,7 +173,7 @@ impl Writer for LengthCalculatingWriter {
 	}
 }
 
-/// Essentially [`std::io::Take`] but a bit simpler and with a method to walk the underlying stream
+/// Essentially `std::io::Take` but a bit simpler and with a method to walk the underlying stream
 /// forward to ensure we always consume exactly the fixed length specified.
 ///
 /// This is not exported to bindings users as manual TLV building is not currently supported in bindings

lightning/src/util/ser_macros.rs

@@ -872,6 +872,7 @@ macro_rules! _init_and_read_tlv_stream {
 ///
 /// [`Readable`]: crate::util::ser::Readable
 /// [`Writeable`]: crate::util::ser::Writeable
+/// [`Vec`]: crate::prelude::Vec
 #[macro_export]
 macro_rules! impl_writeable_tlv_based {
 	($st: ident, {$(($type: expr, $field: ident, $fieldty: tt)),* $(,)*}) => {

lightning/src/util/wakers.rs

@@ -97,11 +97,10 @@ macro_rules! define_callback { ($($bounds: path),*) => {
 /// A callback which is called when a [`Future`] completes.
 ///
 /// Note that this MUST NOT call back into LDK directly, it must instead schedule actions to be
-/// taken later. Rust users should use the [`std::future::Future`] implementation for [`Future`]
-/// instead.
-///
-/// Note that the [`std::future::Future`] implementation may only work for runtimes which schedule
-/// futures when they receive a wake, rather than immediately executing them.
+/// taken later.
+#[cfg_attr(feature = "std", doc = "Rust users should use the [`std::future::Future`] implementation for [`Future`] instead.")]
+#[cfg_attr(feature = "std", doc = "")]
+#[cfg_attr(feature = "std", doc = "Note that the [`std::future::Future`] implementation may only work for runtimes which schedule futures when they receive a wake, rather than immediately executing them.")]
 pub trait FutureCallback : $($bounds +)* {
 	/// The method which is called.
 	fn call(&self);