Skip to content

Commit 58fa3e1

Browse files
hinto-janaihinto-janai
committed
config docs
1 parent 971af40 commit 58fa3e1

File tree

10 files changed

+181
-52
lines changed

10 files changed

+181
-52
lines changed

‎binaries/cuprated/src/config.rs‎

Lines changed: 27 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -49,8 +49,13 @@ const HEADER: &str = r"## ____ _
4949
## \____\__,_| .__/|_| \__,_|\__\___|
5050
## |_|
5151
##
52-
## All these config values can be set to their default by commenting them out with #.
53-
## Some values are already commented out, to set the value remove the # at the start of the line.
52+
## All these config values can be set to
53+
## their default by commenting them out with '#'.
54+
##
55+
## Some values are already commented out,
56+
## to set the value remove the '#' at the start of the line.
57+
##
58+
## For more documentation, see: <https://user.cuprate.org>.
5459
5560
";
5661

@@ -98,43 +103,50 @@ config_struct! {
98103
#[derive(Debug, Deserialize, Serialize, PartialEq)]
99104
#[serde(deny_unknown_fields, default)]
100105
pub struct Config {
101-
/// The network we should run on.
106+
/// The network cuprated should run on.
102107
///
103-
/// Valid values: ["Mainnet", "Testnet" and "Stagenet"]
108+
/// Valid values | "Mainnet", "Testnet", "Stagenet"
104109
pub network: Network,
105110

106111
/// Enable/disable fast sync.
107112
///
108-
/// Fast sync skips verification of old blocks by comparing block hashes to a built-in hash file,
109-
/// disabling this will significantly increase sync time. New blocks are still fully validated.
113+
/// Fast sync skips verification of old blocks by
114+
/// comparing block hashes to a built-in hash file,
115+
/// disabling this will significantly increase sync time.
116+
/// New blocks are still fully validated.
117+
///
118+
/// Type | boolean
119+
/// Valid values | true, false
110120
pub fast_sync: bool,
111121

112122
#[child = true]
113-
/// The tracing/log output config.
123+
/// Configuration for cuprated's logging system, tracing.
124+
///
125+
/// Tracing is used for logging to stdout and files.
114126
pub tracing: TracingConfig,
115127

116128
#[child = true]
117-
/// The tokio config.
129+
/// Configuration for cuprated's asynchronous runtime system, tokio.
118130
///
119-
/// Tokio is the async threadpool, used for network operations and the major service inside `cuprated`.
120-
131+
/// Tokio is used for network operations and the major service inside `cuprated`.
121132
pub tokio: TokioConfig,
133+
122134
#[child = true]
123-
/// The rayon config.
135+
/// Configuration for cuprated's thread-pool system, rayon.
124136
///
125-
/// Rayon is the CPU threadpool, used for CPU intensive tasks.
137+
/// Rayon is used for CPU intensive tasks.
126138
pub rayon: RayonConfig,
127139

128140
#[child = true]
129-
/// The P2P network config.
141+
/// Configuration for cuprated's P2P system.
130142
pub p2p: P2PConfig,
131143

132144
#[child = true]
133-
/// The storage config.
145+
/// Configuration for persistent data storage.
134146
pub storage: StorageConfig,
135147

136148
#[child = true]
137-
/// The filesystem config.
149+
/// Configuration for the file-system.
138150
pub fs: FileSystemConfig,
139151
}
140152
}

‎binaries/cuprated/src/config/fs.rs‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,33 @@ config_struct! {
1313
pub struct FileSystemConfig {
1414
#[comment_out = true]
1515
/// The data directory.
16+
///
17+
/// This directory store the blockchain, transaction pool,
18+
/// log files, and any misc data files.
19+
///
20+
/// The default directories for each OS:
21+
///
22+
/// | OS | Path |
23+
/// |---------|-----------------------------------------------------|
24+
/// | Windows | "C:\Users\Alice\AppData\Roaming\Cuprate\" |
25+
/// | macOS | "/Users/Alice/Library/Application Support/Cuprate/" |
26+
/// | Linux | "/home/alice/.local/share/cuprate/" |
1627
pub data_directory: PathBuf,
1728

1829
#[comment_out = true]
1930
/// The cache directory.
31+
///
32+
/// This directory store cache files.
33+
/// Although not recommended, this directory can be
34+
/// deleted without major disruption to cuprated.
35+
///
36+
/// The default directories for each OS:
37+
///
38+
/// | OS | Path |
39+
/// |---------|-----------------------------------------|
40+
/// | Windows | "C:\Users\Alice\AppData\Local\Cuprate\" |
41+
/// | macOS | "/Users/Alice/Library/Caches/Cuprate/" |
42+
/// | Linux | "/home/alice/.cache/cuprate/" |
2043
pub cache_directory: PathBuf,
2144
}
2245
}

‎binaries/cuprated/src/config/p2p.rs‎

Lines changed: 77 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -32,28 +32,47 @@ config_struct! {
3232
#[serde(deny_unknown_fields, default)]
3333
pub struct BlockDownloaderConfig {
3434
#[comment_out = true]
35-
/// The size in bytes of the buffer between the block downloader and the place which
36-
/// is consuming the downloaded blocks (`cuprated`).
35+
/// The size in bytes of the buffer between the block downloader
36+
/// and the place which is consuming the downloaded blocks (`cuprated`).
3737
///
38-
/// This value is an absolute maximum, once this is reached the block downloader will pause.
38+
/// This value is an absolute maximum,
39+
/// once this is reached the block downloader will pause.
40+
///
41+
/// Type | Number
42+
/// Valid values | >= 0
43+
/// Examples | 1_000_000_000, 5_500_000_000, 500_000_000
3944
pub buffer_bytes: usize,
4045

4146
#[comment_out = true]
42-
/// The size of the in progress queue (in bytes) at which we stop requesting more blocks.
47+
/// The size of the in progress queue (in bytes)
48+
/// at which cuprated stops requesting more blocks.
49+
///
50+
/// The value is _NOT_ an absolute maximum,
51+
/// the in-progress queue could get much larger.
52+
/// This value is only the value cuprated stops requesting more blocks,
53+
/// if cuprated still has requests in progress,
54+
/// it will still accept the response and add the blocks to the queue.
4355
///
44-
/// The value is _NOT_ an absolute maximum, the in progress queue could get much larger. This value
45-
/// is only the value we stop requesting more blocks, if we still have requests in progress we will
46-
/// still accept the response and add the blocks to the queue.
56+
/// Type | Number
57+
/// Valid values | >= 0
58+
/// Examples | 500_000_000, 1_000_000_000,
4759
pub in_progress_queue_bytes: usize,
4860

4961
#[inline = true]
50-
/// The [`Duration`] between checking the client pool for free peers.
62+
/// The target size of a single batch of blocks (in bytes).
63+
///
64+
/// This value must be below 100_000,000,
65+
/// it is not recommended to set it above 30_000_000.
66+
///
67+
/// Type | Number
68+
/// Valid values | 0..100_000,000
5169
pub check_client_pool_interval: Duration,
5270

5371
#[comment_out = true]
54-
/// The target size of a single batch of blocks (in bytes).
72+
/// The duration between checking the client pool for free peers.
5573
///
56-
/// This value must be below 100_000_000, it is not recommended to set it above 30_000_000.
74+
/// Type | Duration
75+
/// Examples | { secs = 30, nanos = 0 }, { secs = 35, nano = 123 }
5776
pub target_batch_bytes: usize,
5877
}
5978
}
@@ -86,7 +105,10 @@ config_struct! {
86105
#[derive(Debug, Deserialize, Serialize, PartialEq)]
87106
#[serde(deny_unknown_fields, default)]
88107
pub struct ClearNetConfig {
89-
/// The IP address we should bind to to listen to connections on.
108+
/// The IP address to bind and listen for connections on.
109+
///
110+
/// Type | IPv4/IPv6 address
111+
/// Examples | "0.0.0.0", "192.168.1.50", "::"
90112
pub listen_on: IpAddr,
91113

92114
#[flatten = true]
@@ -113,24 +135,48 @@ config_struct! {
113135
#[comment_out = true]
114136
/// The number of outbound connections to make and try keep.
115137
///
116-
/// Recommended to keep this value above 12.
138+
/// It's recommended to keep this value above 12.
139+
///
140+
/// Type | Number
141+
/// Valid values | >= 0
142+
/// Examples | 12, 32, 64, 100, 500
117143
pub outbound_connections: usize,
118144

119145
#[comment_out = true]
120-
/// The amount of extra connections we can make if we are under load from the rest of Cuprate.
146+
/// The amount of extra connections to make if cuprated is under load.
147+
///
148+
/// Type | Number
149+
/// Valid values | >= 0
150+
/// Examples | 0, 12, 32, 64, 100, 500
121151
pub extra_outbound_connections: usize,
122152

123153
#[comment_out = true]
124-
/// The maximum amount of inbound connections we should allow.
154+
/// The maximum amount of inbound connections to allow.
155+
///
156+
/// Type | Number
157+
/// Valid values | >= 0
158+
/// Examples | 0, 12, 32, 64, 100, 500
125159
pub max_inbound_connections: usize,
126160

127161
#[comment_out = true]
128-
/// The percent of connections that should be to peers we haven't connected to before.
162+
/// The percent of connections that should be
163+
/// to peers that haven't connected to before.
164+
///
165+
/// 0.0 is 0%.
166+
/// 1.0 is 100%.
167+
///
168+
/// Type | Floating point number
169+
/// Valid values | 0.0..1.0
170+
/// Examples | 0.0, 0.5, 0.123, 0.999, 1.0
129171
pub gray_peers_percent: f64,
130172

131-
/// port to use to accept p2p connections.
173+
/// The port to use to accept incoming P2P connections.
132174
///
133-
/// Set to 0 if you do not want to accept P2P connections.
175+
/// Setting this to 0 will disable incoming P2P connections.
176+
///
177+
/// Type | Number
178+
/// Valid values | 0..65534
179+
/// Examples | 18080, 9999, 5432
134180
pub p2p_port: u16,
135181

136182
#[child = true]
@@ -175,16 +221,28 @@ config_struct! {
175221
pub struct AddressBookConfig {
176222
/// The size of the white peer list.
177223
///
178-
/// The white list holds peers we have connected to before.
224+
/// The white list holds peers that have been connected to before.
225+
///
226+
/// Type | Number
227+
/// Valid values | >= 0
228+
/// Examples | 1000, 500, 241
179229
pub max_white_list_length: usize,
180230

181231
/// The size of the gray peer list.
182232
///
183-
/// The gray peer list holds peers we have been told about but not connected to ourself.
233+
/// The gray peer list holds peers that have been
234+
/// told about but not connected to cuprated.
235+
///
236+
/// Type | Number
237+
/// Valid values | >= 0
238+
/// Examples | 1000, 500, 241
184239
pub max_gray_list_length: usize,
185240

186241
#[inline = true]
187242
/// The time period between address book saves.
243+
///
244+
/// Type | Duration
245+
/// Examples | { secs = 90, nanos = 0 }, { secs = 100, nano = 123 }
188246
pub peer_save_period: Duration,
189247
}
190248
}

‎binaries/cuprated/src/config/rayon.rs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@ config_struct! {
88
#[serde(deny_unknown_fields, default)]
99
pub struct RayonConfig {
1010
#[comment_out = true]
11-
/// The number of threads to use for the rayon thread pool.
11+
/// Type | Number
12+
/// Valid values | >= 1
13+
/// Examples | 1, 8, 14
1214
pub threads: usize,
1315
}
1416
}

‎binaries/cuprated/src/config/storage.rs‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ config_struct! {
1717
/// The amount of reader threads to spawn for the tx-pool and blockchain.
1818
///
1919
/// The tx-pool and blockchain both share a single threadpool.
20+
///
21+
/// Type | Number
22+
/// Valid values | >= 0
23+
/// Examples | 1, 16, 10
2024
pub reader_threads: usize,
2125

2226
#[child = true]
@@ -62,6 +66,10 @@ config_struct! {
6266
pub shared: SharedStorageConfig,
6367

6468
/// The maximum size of the tx-pool.
69+
///
70+
/// Type | Number
71+
/// Valid values | >= 0
72+
/// Examples | 100_000_000, 50_000_000
6573
pub max_txpool_byte_size: usize,
6674
}
6775
}
@@ -83,10 +91,11 @@ config_struct! {
8391
#[comment_out = true]
8492
/// The sync mode of the database.
8593
///
86-
/// Changing this value could make the DB a lot slower when writing data, although
87-
/// using "Safe" makes the DB more durable if there was an unexpected crash.
94+
/// Using "Safe" makes the DB less likely to corrupt
95+
/// if there is an unexpected crash, although it will
96+
/// make DB writes much slower.
8897
///
89-
/// Valid values: ["Fast", "Safe"].
98+
/// Valid values | "Fast", "Safe"
9099
pub sync_mode: SyncMode,
91100
}
92101
}

‎binaries/cuprated/src/config/tokio.rs‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,11 @@ config_struct! {
88
#[serde(deny_unknown_fields, default)]
99
pub struct TokioConfig {
1010
#[comment_out = true]
11-
/// The amount of threads to spawn for the async thread-pool
11+
/// The amount of threads to spawn for the tokio thread-pool.
12+
///
13+
/// Type | Number
14+
/// Valid values | >= 1
15+
/// Examples | 1, 8, 14
1216
pub threads: usize,
1317
}
1418
}

‎binaries/cuprated/src/config/tracing_config.rs‎

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,11 @@ config_struct! {
99
#[serde(deny_unknown_fields, default)]
1010
pub struct TracingConfig {
1111
#[child = true]
12-
/// The stdout logging config.
12+
/// Configuration for cuprated's stdout logging system.
1313
pub stdout: StdoutTracingConfig,
1414

1515
#[child = true]
16-
/// The file logging config.
16+
/// Configuration for cuprated's file logging system.
1717
pub file: FileTracingConfig,
1818
}
1919
}
@@ -22,7 +22,14 @@ config_struct! {
2222
#[derive(Debug, Deserialize, Serialize, Eq, PartialEq)]
2323
#[serde(deny_unknown_fields, default)]
2424
pub struct StdoutTracingConfig {
25-
/// The default minimum log level.
25+
/// The minimum log level for stdout.
26+
///
27+
/// Levels below this one will not be shown.
28+
/// "error" is the highest level only showing errors,
29+
/// "trace" is the lowest showing as much as possible.
30+
///
31+
/// Type | Level
32+
/// Valid values | "error", "warn", "info", "debug", "trace"
2633
##[serde(with = "level_filter_serde")]
2734
pub level: LevelFilter,
2835
}
@@ -40,12 +47,24 @@ config_struct! {
4047
#[derive(Debug, Deserialize, Serialize, Eq, PartialEq)]
4148
#[serde(deny_unknown_fields, default)]
4249
pub struct FileTracingConfig {
43-
/// The default minimum log level.
50+
/// The minimum log level for file logs.
51+
///
52+
/// Levels below this one will not be shown.
53+
/// "error" is the highest level only showing errors,
54+
/// "trace" is the lowest showing as much as possible.
55+
///
56+
/// Type | Level
57+
/// Valid values | "error", "warn", "info", "debug", "trace"
4458
##[serde(with = "level_filter_serde")]
4559
pub level: LevelFilter,
4660

47-
/// The maximum amount of log files to keep, once this number is passed the oldest file
48-
/// will be deleted.
61+
/// The maximum amount of log files to keep.
62+
///
63+
/// Once this number is passed the oldest file will be deleted.
64+
///
65+
/// Type | Number
66+
/// Valid values | >= 0
67+
/// Examples | 0, 7, 200
4968
pub max_log_files: usize,
5069
}
5170
}

0 commit comments

Comments
 (0)