From 00daeba848ef2dbc6cdedf3dbc43e7be9078d886 Mon Sep 17 00:00:00 2001
From: jp1ac4 <121959000+jp1ac4@users.noreply.github.com>
Date: Wed, 16 Aug 2023 15:51:10 +0100
Subject: [PATCH] Add some docstrings

---
 gui/src/app/config.rs         |  1 +
 gui/src/app/mod.rs            |  2 ++
 gui/src/installer/mod.rs      |  1 +
 gui/src/installer/step/mod.rs | 10 ++++++++++
 gui/src/utils/mod.rs          |  2 ++
 5 files changed, 16 insertions(+)

diff --git a/gui/src/app/config.rs b/gui/src/app/config.rs
index 008f502e9..1dfd52d93 100644
--- a/gui/src/app/config.rs
+++ b/gui/src/app/config.rs
@@ -3,6 +3,7 @@ use serde::{Deserialize, Serialize};
 use std::path::{Path, PathBuf};
 use tracing_subscriber::filter;
 
+/// Config required to start internal bitcoind.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct InternalBitcoindExeConfig {
     /// Internal bitcoind executable path.
diff --git a/gui/src/app/mod.rs b/gui/src/app/mod.rs
index e08060aae..2594b45ed 100644
--- a/gui/src/app/mod.rs
+++ b/gui/src/app/mod.rs
@@ -223,6 +223,7 @@ impl App {
     }
 }
 
+/// Start internal bitcoind for the given network.
 pub fn start_internal_bitcoind(
     network: &bitcoin::Network,
     exe_config: InternalBitcoindExeConfig,
@@ -240,6 +241,7 @@ pub fn start_internal_bitcoind(
         .spawn()
 }
 
+/// Stop (internal) bitcoind.
 pub fn stop_internal_bitcoind(bitcoind_config: &BitcoindConfig) {
     match liana::BitcoinD::new(bitcoind_config, "internal_bitcoind_stop".to_string()) {
         Ok(bitcoind) => {
diff --git a/gui/src/installer/mod.rs b/gui/src/installer/mod.rs
index 4ac834d2a..ad04e9c8a 100644
--- a/gui/src/installer/mod.rs
+++ b/gui/src/installer/mod.rs
@@ -257,6 +257,7 @@ pub fn daemon_check(cfg: liana::config::Config) -> Result<(), Error> {
     }
 }
 
+/// Data directory used by internal bitcoind.
 pub fn internal_bitcoind_datadir(liana_datadir: &PathBuf) -> PathBuf {
     let mut datadir = PathBuf::from(liana_datadir);
     datadir.push("bitcoind_datadir");
diff --git a/gui/src/installer/step/mod.rs b/gui/src/installer/step/mod.rs
index 50055cdf3..264061113 100644
--- a/gui/src/installer/step/mod.rs
+++ b/gui/src/installer/step/mod.rs
@@ -118,9 +118,12 @@ pub struct SelectBitcoindTypeStep {
     error: Option<String>,
 }
 
+/// Default prune value used by internal bitcoind.
 pub const PRUNE_DEFAULT: u32 = 15_000;
+/// Default ports used by bitcoind across all networks.
 pub const BITCOIND_DEFAULT_PORTS: [u16; 8] = [8332, 8333, 18332, 18333, 18443, 18444, 38332, 38333];
 
+/// Represents section for a single network in `bitcoin.conf` file.
 #[derive(Debug, Clone)]
 pub struct InternalBitcoindNetworkConfig {
     rpc_port: u16,
@@ -128,6 +131,7 @@ pub struct InternalBitcoindNetworkConfig {
     prune: u32,
 }
 
+/// Represents the `bitcoin.conf` file to be used by internal bitcoind.
 #[derive(Debug, Clone)]
 pub struct InternalBitcoindConfig {
     networks: HashMap<Network, InternalBitcoindNetworkConfig>,
@@ -250,12 +254,14 @@ impl InternalBitcoindConfig {
     }
 }
 
+/// Path of the `bitcoin.conf` file used by internal bitcoind.
 fn internal_bitcoind_config_path(liana_datadir: &PathBuf) -> PathBuf {
     let mut config_path = internal_bitcoind_datadir(liana_datadir);
     config_path.push("bitcoin.conf");
     config_path
 }
 
+/// Path of the cookie file used by internal bitcoind on a given network.
 fn internal_bitcoind_cookie_path(bitcoind_datadir: &Path, network: &Network) -> PathBuf {
     let mut cookie_path = bitcoind_datadir.to_path_buf();
     if let Some(dir) = bitcoind_network_dir(network) {
@@ -265,6 +271,7 @@ fn internal_bitcoind_cookie_path(bitcoind_datadir: &Path, network: &Network) ->
     cookie_path
 }
 
+/// RPC address for internal bitcoind.
 fn internal_bitcoind_address(rpc_port: u16) -> SocketAddr {
     SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), rpc_port)
 }
@@ -322,10 +329,12 @@ fn bitcoind_default_address(network: &Network) -> String {
     }
 }
 
+/// Looks for bitcoind executable path and returns `None` if not found.
 fn bitcoind_exe_path() -> Option<PathBuf> {
     which::which("bitcoind").ok()
 }
 
+/// Get available port that is valid for use by internal bitcoind.
 // Modified from https://github.com/RCasatta/bitcoind/blob/f047740d7d0af935ff7360cf77429c5f294cfd59/src/lib.rs#L435
 pub fn get_available_port() -> Result<u16, Error> {
     // Perform multiple attempts to get a valid port.
@@ -346,6 +355,7 @@ pub fn get_available_port() -> Result<u16, Error> {
     ))
 }
 
+/// Checks if port is valid for use by internal bitcoind.
 pub fn port_is_valid(port: &u16) -> bool {
     !BITCOIND_DEFAULT_PORTS.contains(port)
 }
diff --git a/gui/src/utils/mod.rs b/gui/src/utils/mod.rs
index c4448721e..55b5a4b2b 100644
--- a/gui/src/utils/mod.rs
+++ b/gui/src/utils/mod.rs
@@ -6,6 +6,8 @@ pub mod sandbox;
 #[cfg(test)]
 pub mod mock;
 
+/// Polls for a file's existence at given interval up to a maximum number of polls.
+/// Returns `true` once file exists and otherwise `false`.
 pub fn poll_for_file(path: &Path, interval_millis: u64, max_polls: u16) -> bool {
     for i in 0..max_polls {
         if path.exists() {