books: user-book for cuprated 0.0.2

binaries/cuprated/src/config.rs

@@ -49,8 +49,13 @@ const HEADER: &str = r"##     ____                      _
 ##    \____\__,_| .__/|_|  \__,_|\__\___|
 ##              |_|
 ##
-## All these config values can be set to their default by commenting them out with #.
-## Some values are already commented out, to set the value remove the # at the start of the line.
+## All these config values can be set to
+## their default by commenting them out with '#'.
+##
+## Some values are already commented out,
+## to set the value remove the '#' at the start of the line.
+##
+## For more documentation, see: <https://user.cuprate.org>.
 
 ";
 
@@ -98,43 +103,50 @@ config_struct! {
     #[derive(Debug, Deserialize, Serialize, PartialEq)]
     #[serde(deny_unknown_fields, default)]
     pub struct Config {
-        /// The network we should run on.
+        /// The network cuprated should run on.
         ///
-        /// Valid values: ["Mainnet", "Testnet" and "Stagenet"]
+        /// Valid values | "Mainnet", "Testnet", "Stagenet"
         pub network: Network,
 
         /// Enable/disable fast sync.
         ///
-        /// Fast sync skips verification of old blocks by comparing block hashes to a built-in hash file,
-        /// disabling this will significantly increase sync time. New blocks are still fully validated.
+        /// Fast sync skips verification of old blocks by
+        /// comparing block hashes to a built-in hash file,
+        /// disabling this will significantly increase sync time.
+        /// New blocks are still fully validated.
+        ///
+        /// Type         | boolean
+        /// Valid values | true, false
         pub fast_sync: bool,
 
         #[child = true]
-        /// The tracing/log output config.
+        /// Configuration for cuprated's logging system, tracing.
+        ///
+        /// Tracing is used for logging to stdout and files.
         pub tracing: TracingConfig,
 
         #[child = true]
-        /// The tokio config.
+        /// Configuration for cuprated's asynchronous runtime system, tokio.
         ///
-        /// Tokio is the async threadpool, used for network operations and the major service inside `cuprated`.
-
+        /// Tokio is used for network operations and the major services inside `cuprated`.
         pub tokio: TokioConfig,
+
         #[child = true]
-        /// The rayon config.
+        /// Configuration for cuprated's thread-pool system, rayon.
         ///
-        /// Rayon is the CPU threadpool, used for CPU intensive tasks.
+        /// Rayon is used for CPU intensive tasks.
         pub rayon: RayonConfig,
 
         #[child = true]
-        /// The P2P network config.
+        /// Configuration for cuprated's P2P system.
         pub p2p: P2PConfig,
 
         #[child = true]
-        /// The storage config.
+        /// Configuration for persistent data storage.
         pub storage: StorageConfig,
 
         #[child = true]
-        /// The filesystem config.
+        /// Configuration for the file-system.
         pub fs: FileSystemConfig,
     }
 }

binaries/cuprated/src/config/fs.rs

@@ -13,10 +13,33 @@ config_struct! {
     pub struct FileSystemConfig {
         #[comment_out = true]
         /// The data directory.
+        ///
+        /// This directory store the blockchain, transaction pool,
+        /// log files, and any misc data files.
+        ///
+        /// The default directories for each OS:
+        ///
+        /// | OS      | Path                                                |
+        /// |---------|-----------------------------------------------------|
+        /// | Windows | "C:\Users\Alice\AppData\Roaming\Cuprate\"           |
+        /// | macOS   | "/Users/Alice/Library/Application Support/Cuprate/" |
+        /// | Linux   | "/home/alice/.local/share/cuprate/"                 |
         pub data_directory: PathBuf,
 
         #[comment_out = true]
         /// The cache directory.
+        ///
+        /// This directory store cache files.
+        /// Although not recommended, this directory can be
+        /// deleted without major disruption to cuprated.
+        ///
+        /// The default directories for each OS:
+        ///
+        /// | OS      | Path                                    |
+        /// |---------|-----------------------------------------|
+        /// | Windows | "C:\Users\Alice\AppData\Local\Cuprate\" |
+        /// | macOS   | "/Users/Alice/Library/Caches/Cuprate/"  |
+        /// | Linux   | "/home/alice/.cache/cuprate/"           |
         pub cache_directory: PathBuf,
     }
 }

binaries/cuprated/src/config/macros.rs

@@ -8,6 +8,57 @@ use toml_edit::TableLike;
 /// - `#[child = true]`: writes the doc comments for all fields in the child struct.
 /// - `#[inline = true]`: inlines the struct into `{}` instead of having a separate `[]` header.
 /// - `#[comment_out = true]`: comments out the field.
+///
+/// # Documentation
+/// Consider using the following style when adding documentation:
+///
+/// ```rust
+/// struct Config {
+///     /// BRIEF DESCRIPTION.
+///     ///
+///     /// (optional) LONGER DESCRIPTION.
+//      ///
+///     /// Type         | (optional) FIELD TYPE
+///     /// Valid values | EXPRESSION REPRESENTING VALID VALUES
+///     /// Examples     | (optional) A FEW EXAMPLE VALUES
+///     field: (),
+/// }
+/// ```
+///
+/// For example:
+/// ```rust
+/// struct Config {
+///     /// Enable/disable fast sync.
+///     ///
+///     /// Fast sync skips verification of old blocks by
+///     /// comparing block hashes to a built-in hash file,
+///     /// disabling this will significantly increase sync time.
+///     /// New blocks are still fully validated.
+///     ///
+///     /// Type         | boolean
+///     /// Valid values | true, false
+///     fast_sync: bool,
+/// }
+/// ```
+///
+/// Language for types:
+///
+/// | Rust type    | Wording used in user-book |
+/// |--------------|---------------------------|
+/// | bool         | boolean
+/// | u{8-64}      | Number
+/// | i{8-64}      | Signed number
+/// | f{32,64}     | Floating point number
+/// | str, String  | String
+/// | enum, struct | `DataStructureName` (e.g. `Duration`) or $DESCRIPTION (e.g. `IP address`)
+///
+/// If some fields are redundant or unnecessary, do not add them.
+///
+/// # Field documentation length
+/// In order to prevent wrapping/scrollbars in the user book and in editors,
+/// add newlines when a documentation line crosses ~70 characters, around this long:
+///
+/// `----------------------------------------------------------------------`
 macro_rules! config_struct {
     (
         $(#[$meta:meta])*

binaries/cuprated/src/config/p2p.rs

@@ -32,28 +32,47 @@ config_struct! {
     #[serde(deny_unknown_fields, default)]
     pub struct BlockDownloaderConfig {
         #[comment_out = true]
-        /// The size in bytes of the buffer between the block downloader and the place which
-        /// is consuming the downloaded blocks (`cuprated`).
+        /// The size in bytes of the buffer between the block downloader
+        /// and the place which is consuming the downloaded blocks (`cuprated`).
         ///
-        /// This value is an absolute maximum, once this is reached the block downloader will pause.
+        /// This value is an absolute maximum,
+        /// once this is reached the block downloader will pause.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 1_000_000_000, 5_500_000_000, 500_000_000
         pub buffer_bytes: usize,
 
         #[comment_out = true]
-        /// The size of the in progress queue (in bytes) at which we stop requesting more blocks.
+        /// The size of the in progress queue (in bytes)
+        /// at which cuprated stops requesting more blocks.
+        ///
+        /// The value is _NOT_ an absolute maximum,
+        /// the in-progress queue could get much larger.
+        /// This value is only the value cuprated stops requesting more blocks,
+        /// if cuprated still has requests in progress,
+        /// it will still accept the response and add the blocks to the queue.
         ///
-        /// The value is _NOT_ an absolute maximum, the in progress queue could get much larger. This value
-        /// is only the value we stop requesting more blocks, if we still have requests in progress we will
-        /// still accept the response and add the blocks to the queue.
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 500_000_000, 1_000_000_000,
         pub in_progress_queue_bytes: usize,
 
         #[inline = true]
-        /// The [`Duration`] between checking the client pool for free peers.
+        /// The duration between checking the client pool for free peers.
+        ///
+        /// Type     | Duration
+        /// Examples | { secs = 30, nanos = 0 }, { secs = 35, nano = 123 }
         pub check_client_pool_interval: Duration,
 
         #[comment_out = true]
         /// The target size of a single batch of blocks (in bytes).
         ///
-        /// This value must be below 100_000_000, it is not recommended to set it above 30_000_000.
+        /// This value must be below 100_000,000,
+        /// it is not recommended to set it above 30_000_000.
+        ///
+        /// Type         | Number
+        /// Valid values | 0..100_000,000
         pub target_batch_bytes: usize,
     }
 }
@@ -86,7 +105,10 @@ config_struct! {
     #[derive(Debug, Deserialize, Serialize, PartialEq)]
     #[serde(deny_unknown_fields, default)]
     pub struct ClearNetConfig {
-        /// The IP address we should bind to to listen to connections on.
+        /// The IP address to bind and listen for connections on.
+        ///
+        /// Type     | IPv4/IPv6 address
+        /// Examples | "0.0.0.0", "192.168.1.50", "::"
         pub listen_on: IpAddr,
 
         #[flatten = true]
@@ -113,24 +135,48 @@ config_struct! {
         #[comment_out = true]
         /// The number of outbound connections to make and try keep.
         ///
-        /// Recommended to keep this value above 12.
+        /// It's recommended to keep this value above 12.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 12, 32, 64, 100, 500
         pub outbound_connections: usize,
 
         #[comment_out = true]
-        /// The amount of extra connections we can make if we are under load from the rest of Cuprate.
+        /// The amount of extra connections to make if cuprated is under load.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 0, 12, 32, 64, 100, 500
         pub extra_outbound_connections: usize,
 
         #[comment_out = true]
-        /// The maximum amount of inbound connections we should allow.
+        /// The maximum amount of inbound connections to allow.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 0, 12, 32, 64, 100, 500
         pub max_inbound_connections: usize,
 
         #[comment_out = true]
-        /// The percent of connections that should be to peers we haven't connected to before.
+        /// The percent of connections that should be
+        /// to peers that haven't connected to before.
+        ///
+        /// 0.0 is 0%.
+        /// 1.0 is 100%.
+        ///
+        /// Type         | Floating point number
+        /// Valid values | 0.0..1.0
+        /// Examples     | 0.0, 0.5, 0.123, 0.999, 1.0
         pub gray_peers_percent: f64,
 
-        /// port to use to accept p2p connections.
+        /// The port to use to accept incoming P2P connections.
+        ///
+        /// Setting this to 0 will disable incoming P2P connections.
         ///
-        /// Set to 0 if you do not want to accept P2P connections.
+        /// Type         | Number
+        /// Valid values | 0..65534
+        /// Examples     | 18080, 9999, 5432
         pub p2p_port: u16,
 
         #[child = true]
@@ -175,16 +221,28 @@ config_struct! {
     pub struct AddressBookConfig {
         /// The size of the white peer list.
         ///
-        /// The white list holds peers we have connected to before.
+        /// The white list holds peers that have been connected to before.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 1000, 500, 241
         pub max_white_list_length: usize,
 
         /// The size of the gray peer list.
         ///
-        /// The gray peer list holds peers we have been told about but not connected to ourself.
+        /// The gray peer list holds peers that have been
+        /// told about but not connected to cuprated.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 1000, 500, 241
         pub max_gray_list_length: usize,
 
         #[inline = true]
         /// The time period between address book saves.
+        ///
+        /// Type     | Duration
+        /// Examples | { secs = 90, nanos = 0 }, { secs = 100, nano = 123 }
         pub peer_save_period: Duration,
     }
 }

binaries/cuprated/src/config/rayon.rs

@@ -8,7 +8,9 @@ config_struct! {
     #[serde(deny_unknown_fields, default)]
     pub struct RayonConfig {
         #[comment_out = true]
-        /// The number of threads to use for the rayon thread pool.
+        /// Type         | Number
+        /// Valid values | >= 1
+        /// Examples     | 1, 8, 14
         pub threads: usize,
     }
 }

binaries/cuprated/src/config/storage.rs

@@ -17,6 +17,10 @@ config_struct! {
         /// The amount of reader threads to spawn for the tx-pool and blockchain.
         ///
         /// The tx-pool and blockchain both share a single threadpool.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 1, 16, 10
         pub reader_threads: usize,
 
         #[child = true]
@@ -62,6 +66,10 @@ config_struct! {
         pub shared: SharedStorageConfig,
 
         /// The maximum size of the tx-pool.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 0
+        /// Examples     | 100_000_000, 50_000_000
         pub max_txpool_byte_size: usize,
     }
 }
@@ -83,10 +91,11 @@ config_struct! {
         #[comment_out = true]
         /// The sync mode of the database.
         ///
-        /// Changing this value could make the DB a lot slower when writing data, although
-        /// using "Safe" makes the DB more durable if there was an unexpected crash.
+        /// Using "Safe" makes the DB less likely to corrupt
+        /// if there is an unexpected crash, although it will
+        /// make DB writes much slower.
         ///
-        /// Valid values: ["Fast", "Safe"].
+        /// Valid values | "Fast", "Safe"
         pub sync_mode: SyncMode,
     }
 }

binaries/cuprated/src/config/tokio.rs

@@ -8,7 +8,11 @@ config_struct! {
     #[serde(deny_unknown_fields, default)]
     pub struct TokioConfig {
         #[comment_out = true]
-        /// The amount of threads to spawn for the async thread-pool
+        /// The amount of threads to spawn for the tokio thread-pool.
+        ///
+        /// Type         | Number
+        /// Valid values | >= 1
+        /// Examples     | 1, 8, 14
         pub threads: usize,
     }
 }