Merge pull request #835 from tnull/2026-03-improve-docs

Improve `Builder` and `Config` docs

Author: tnull

src/builder.rs

@@ -236,9 +236,40 @@ impl std::error::Error for BuildError {}
 /// the getgo.
 ///
 /// ### Defaults
-/// - Wallet entropy is sourced from a `keys_seed` file located under [`Config::storage_dir_path`]
+/// - See [`Config`] for the default values of all configuration options.
 /// - Chain data is sourced from the Esplora endpoint `https://blockstream.info/api`
 /// - Gossip data is sourced via the peer-to-peer network
+/// - Logs are written to the filesystem (see [Logging] below)
+///
+/// ### Storage
+///
+/// Several `build` methods are available depending on the desired storage backend:
+/// - [`build`] uses an SQLite database (recommended default).
+/// - [`build_with_fs_store`] uses a filesystem-based store.
+/// - [`build_with_vss_store`] and variants use a [VSS] remote store (**experimental**).
+/// - [`build_with_store`] allows providing a custom [`KVStore`] implementation.
+///
+/// ### Logging
+///
+/// By default, logs are written to the filesystem via an internal file logger at
+/// [`DEFAULT_LOG_LEVEL`]. The log file path and level can be customized via
+/// [`set_filesystem_logger`].
+///
+/// Alternatively, logs can be written to the [`log`] facade via [`set_log_facade_logger`], or to
+/// a custom [`LogWriter`] via [`set_custom_logger`].
+///
+/// [`build`]: Self::build
+/// [`build_with_fs_store`]: Self::build_with_fs_store
+/// [`build_with_vss_store`]: Self::build_with_vss_store
+/// [`build_with_store`]: Self::build_with_store
+/// [VSS]: https://github.com/lightningdevkit/vss-server/blob/main/README.md
+/// [`KVStore`]: lightning::util::persist::KVStore
+/// [`DEFAULT_LOG_LEVEL`]: crate::config::DEFAULT_LOG_LEVEL
+/// [`set_filesystem_logger`]: Self::set_filesystem_logger
+/// [`set_log_facade_logger`]: Self::set_log_facade_logger
+/// [`set_custom_logger`]: Self::set_custom_logger
+/// [`log`]: https://crates.io/crates/log
+/// [Logging]: #logging
 #[derive(Debug)]
 pub struct NodeBuilder {
 	config: Config,
@@ -472,6 +503,10 @@ impl NodeBuilder {
 	/// If set, the `max_log_level` sets the maximum log level. Otherwise, the latter defaults to
 	/// [`DEFAULT_LOG_LEVEL`].
 	///
+	/// **Note:** Log rotation and pruning are the responsibility of the user and are not handled
+	/// internally. For example, UNIX system tooling such as `logrotate` and `cron` can be used to
+	/// manage log file sizes and retention.
+	///
 	/// [`DEFAULT_LOG_FILENAME`]: crate::config::DEFAULT_LOG_FILENAME
 	pub fn set_filesystem_logger(
 		&mut self, log_file_path: Option<String>, max_log_level: Option<LogLevel>,
@@ -764,9 +799,41 @@ impl NodeBuilder {
 /// the getgo.
 ///
 /// ### Defaults
-/// - Wallet entropy is sourced from a `keys_seed` file located under [`Config::storage_dir_path`]
+/// - See [`Config`] for the default values of all configuration options.
 /// - Chain data is sourced from the Esplora endpoint `https://blockstream.info/api`
 /// - Gossip data is sourced via the peer-to-peer network
+/// - Logs are written to the filesystem (see [Logging] below)
+///
+/// ### Storage
+///
+/// Several `build` methods are available depending on the desired storage backend:
+/// - [`build`] uses an SQLite database (recommended default).
+/// - [`build_with_fs_store`] uses a filesystem-based store.
+/// - [`build_with_vss_store`] and variants use a [VSS] remote store (**experimental**).
+/// - [`build_with_store`] allows providing a custom [`KVStore`] implementation.
+///
+/// ### Logging
+///
+/// By default, logs are written to the filesystem via an internal file logger at
+/// [`DEFAULT_LOG_LEVEL`]. The log file path and level can be customized via
+/// [`set_filesystem_logger`].
+///
+/// Alternatively, logs can be written to the [`log`] facade via [`set_log_facade_logger`], or to
+/// a custom [`LogWriter`] via [`set_custom_logger`].
+///
+/// [`build`]: Self::build
+/// [`build_with_fs_store`]: Self::build_with_fs_store
+/// [`build_with_vss_store`]: Self::build_with_vss_store
+/// [`build_with_store`]: Self::build_with_store
+/// [VSS]: https://github.com/lightningdevkit/vss-server/blob/main/README.md
+/// [`KVStore`]: lightning::util::persist::KVStore
+/// [`DEFAULT_LOG_LEVEL`]: crate::config::DEFAULT_LOG_LEVEL
+/// [`set_filesystem_logger`]: Self::set_filesystem_logger
+/// [`set_log_facade_logger`]: Self::set_log_facade_logger
+/// [`set_custom_logger`]: Self::set_custom_logger
+/// [`log`]: https://crates.io/crates/log
+/// [Logging]: #logging
+/// [Storage]: #storage
 #[derive(Debug)]
 #[cfg(feature = "uniffi")]
 pub struct ArcedNodeBuilder {
@@ -937,6 +1004,10 @@ impl ArcedNodeBuilder {
 	/// If set, the `max_log_level` sets the maximum log level. Otherwise, the latter defaults to
 	/// [`DEFAULT_LOG_LEVEL`].
 	///
+	/// **Note:** Log rotation and pruning are the responsibility of the user and are not handled
+	/// internally. For example, UNIX system tooling such as `logrotate` and `cron` can be used to
+	/// manage log file sizes and retention.
+	///
 	/// [`DEFAULT_LOG_FILENAME`]: crate::config::DEFAULT_LOG_FILENAME
 	pub fn set_filesystem_logger(
 		&self, log_file_path: Option<String>, log_level: Option<LogLevel>,

src/config.rs

@@ -119,17 +119,12 @@ pub(crate) const LNURL_AUTH_TIMEOUT_SECS: u64 = 15;
 /// | Parameter                              | Value              |
 /// |----------------------------------------|--------------------|
 /// | `storage_dir_path`                     | /tmp/ldk_node/     |
-/// | `log_dir_path`                         | None               |
 /// | `network`                              | Bitcoin            |
 /// | `listening_addresses`                  | None               |
+/// | `announcement_addresses`               | None               |
 /// | `node_alias`                           | None               |
-/// | `default_cltv_expiry_delta`            | 144                |
-/// | `onchain_wallet_sync_interval_secs`    | 80                 |
-/// | `wallet_sync_interval_secs`            | 30                 |
-/// | `fee_rate_cache_update_interval_secs`  | 600                |
 /// | `trusted_peers_0conf`                  | []                 |
 /// | `probing_liquidity_limit_multiplier`   | 3                  |
-/// | `log_level`                            | Debug              |
 /// | `anchor_channels_config`               | Some(..)           |
 /// | `route_parameters`                     | None               |
 /// | `tor_config`                           | None               |
@@ -273,7 +268,7 @@ pub struct AnchorChannelsConfig {
 	/// [`AnchorChannelsConfig::trusted_peers_no_reserve`], we will always try to spend the Anchor
 	/// outputs with *any* on-chain funds available, i.e., the total reserve value as well as any
 	/// spendable funds available in the on-chain wallet. Therefore, this per-channel multiplier is
-	/// really a emergency reserve that we maintain at all time to reduce reduce the risk of
+	/// really an emergency reserve that we maintain at all time to reduce the risk of
 	/// insufficient funds at time of a channel closure. To this end, we will refuse to open
 	/// outbound or accept inbound channels if we don't have sufficient on-chain funds available to
 	/// cover the additional reserve requirement.

src/lib.rs

@@ -11,7 +11,7 @@
 //! A ready-to-go Lightning node library built using [LDK](https://lightningdevkit.org/) and
 //! [BDK](https://bitcoindevkit.org/).
 //!
-//! LDK Node is a non-custodial Lightning node in library form. Its central goal is to provide a
+//! LDK Node is a self-custodial Lightning node in library form. Its central goal is to provide a
 //! small, simple, and straightforward interface that enables users to easily set up and run a
 //! Lightning node with an integrated on-chain wallet. While minimalism is at its core, LDK Node
 //! aims to be sufficiently modular and configurable to be useful for a variety of use cases.