chore(docs): add minor improvements on docs

- standardize dependencies on `Cargo.toml`, and sort it.
- add a couple of documentation improvements, on missing docstring fields.

Author: oleonardolima

.rustfmt.toml

@@ -0,0 +1,3 @@
+wrap_comments = true
+format_code_in_doc_comments = true
+edition = "2021"

Cargo.toml

@@ -17,26 +17,28 @@ name = "esplora_client"
 path = "src/lib.rs"
 
 [dependencies]
-serde = { version = "1.0", features = ["derive"] }
 bitcoin = { version = "0.32", features = ["serde", "std"], default-features = false }
-hex = { package = "hex-conservative", version = "0.2" }
-log = "^0.4"
+hex = { version = "0.2", package = "hex-conservative" }
+log = { version = "^0.4" }
 minreq = { version = "2.11.0", features = ["json-using-serde"], optional = true }
-reqwest = { version = "0.11", optional = true, default-features = false, features = ["json"] }
+reqwest = { version = "0.11", features = ["json"], default-features = false, optional = true }
+serde = { version = "1.0", features = ["derive"] }
 
 [dev-dependencies]
-serde_json = "1.0"
-tokio = { version = "1.20.1", features = ["full"] }
 electrsd = { version = "0.28.0", features = ["legacy", "esplora_a33e97e1", "bitcoind_25_0"] }
-lazy_static = "1.4.0"
+lazy_static = { version = "1.4.0"}
+serde_json = { version = "1.0"}
+tokio = { version = "1.20.1", features = ["full"] }
 
 [features]
 default = ["blocking", "async", "async-https"]
+
 blocking = ["minreq", "minreq/proxy"]
 blocking-https = ["blocking", "minreq/https"]
 blocking-https-rustls = ["blocking", "minreq/https-rustls"]
 blocking-https-native = ["blocking", "minreq/https-native"]
 blocking-https-bundled = ["blocking", "minreq/https-bundled"]
+
 async = ["reqwest", "reqwest/socks"]
 async-https = ["async", "reqwest/default-tls"]
 async-https-native = ["async", "reqwest/native-tls"]

src/api.rs

@@ -1,6 +1,6 @@
-//! structs from the esplora API
+//! Structs from the Esplora API
 //!
-//! see: <https://github.com/Blockstream/esplora/blob/master/API.md>
+//! See: <https://github.com/Blockstream/esplora/blob/master/API.md>
 
 pub use bitcoin::consensus::{deserialize, serialize};
 pub use bitcoin::hex::FromHex;

src/async.rs

@@ -30,12 +30,14 @@ use crate::{BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus
 
 #[derive(Debug, Clone)]
 pub struct AsyncClient {
+    /// The URL of the Esplora Server.
     url: String,
+    /// The inner [`reqwest::Client`] to make HTTP requests.
     client: Client,
 }
 
 impl AsyncClient {
-    /// build an async client from a builder
+    /// Build an async client from a builder
     pub fn from_builder(builder: Builder) -> Result<Self, Error> {
         let mut client_builder = Client::builder();
 
@@ -64,7 +66,7 @@ impl AsyncClient {
         Ok(Self::from_client(builder.base_url, client_builder.build()?))
     }
 
-    /// build an async client from the base url and [`Client`]
+    /// Build an async client from the base url and [`Client`]
     pub fn from_client(url: String, client: Client) -> Self {
         AsyncClient { url, client }
     }
@@ -100,7 +102,8 @@ impl AsyncClient {
         }
     }
 
-    /// Get a [`Txid`] of a transaction given its index in a block with a given hash.
+    /// Get a [`Txid`] of a transaction given its index in a block with a given
+    /// hash.
     pub async fn get_txid_at_block_index(
         &self,
         block_hash: &BlockHash,
@@ -222,7 +225,8 @@ impl AsyncClient {
         }
     }
 
-    /// Get a merkle inclusion proof for a [`Transaction`] with the given [`Txid`].
+    /// Get a merkle inclusion proof for a [`Transaction`] with the given
+    /// [`Txid`].
     pub async fn get_merkle_proof(&self, tx_hash: &Txid) -> Result<Option<MerkleProof>, Error> {
         let resp = self
             .client
@@ -244,7 +248,8 @@ impl AsyncClient {
         }
     }
 
-    /// Get a [`MerkleBlock`] inclusion proof for a [`Transaction`] with the given [`Txid`].
+    /// Get a [`MerkleBlock`] inclusion proof for a [`Transaction`] with the
+    /// given [`Txid`].
     pub async fn get_merkle_block(&self, tx_hash: &Txid) -> Result<Option<MerkleBlock>, Error> {
         let resp = self
             .client
@@ -267,7 +272,8 @@ impl AsyncClient {
         }
     }
 
-    /// Get the spending status of an output given a [`Txid`] and the output index.
+    /// Get the spending status of an output given a [`Txid`] and the output
+    /// index.
     pub async fn get_output_status(
         &self,
         txid: &Txid,
@@ -372,7 +378,8 @@ impl AsyncClient {
 
     /// Get confirmed transaction history for the specified address/scripthash,
     /// sorted with newest first. Returns 25 transactions per page.
-    /// More can be requested by specifying the last txid seen by the previous query.
+    /// More can be requested by specifying the last txid seen by the previous
+    /// query.
     pub async fn scripthash_txs(
         &self,
         script: &Script,
@@ -399,8 +406,8 @@ impl AsyncClient {
         }
     }
 
-    /// Get an map where the key is the confirmation target (in number of blocks)
-    /// and the value is the estimated feerate (in sat/vB).
+    /// Get an map where the key is the confirmation target (in number of
+    /// blocks) and the value is the estimated feerate (in sat/vB).
     pub async fn get_fee_estimates(&self) -> Result<HashMap<u16, f64>, Error> {
         let resp = self
             .client
@@ -418,10 +425,11 @@ impl AsyncClient {
         }
     }
 
-    /// Gets some recent block summaries starting at the tip or at `height` if provided.
+    /// Gets some recent block summaries starting at the tip or at `height` if
+    /// provided.
     ///
-    /// The maximum number of summaries returned depends on the backend itself: esplora returns `10`
-    /// while [mempool.space](https://mempool.space/docs/api) returns `15`.
+    /// The maximum number of summaries returned depends on the backend itself:
+    /// esplora returns `10` while [mempool.space](https://mempool.space/docs/api) returns `15`.
     pub async fn get_blocks(&self, height: Option<u32>) -> Result<Vec<BlockSummary>, Error> {
         let url = match height {
             Some(height) => format!("{}/blocks/{}", self.url, height),

src/blocking.rs

@@ -31,6 +31,7 @@ use crate::{BlockStatus, BlockSummary, Builder, Error, MerkleProof, OutputStatus
 
 #[derive(Debug, Clone)]
 pub struct BlockingClient {
+    /// The URL of the Esplora server.
     url: String,
     /// The proxy is ignored when targeting `wasm32`.
     pub proxy: Option<String>,
@@ -41,7 +42,7 @@ pub struct BlockingClient {
 }
 
 impl BlockingClient {
-    /// build a blocking client from a [`Builder`]
+    /// Build a blocking client from a [`Builder`]
     pub fn from_builder(builder: Builder) -> Self {
         Self {
             url: builder.base_url,
@@ -199,7 +200,8 @@ impl BlockingClient {
         }
     }
 
-    /// Get a [`Txid`] of a transaction given its index in a block with a given hash.
+    /// Get a [`Txid`] of a transaction given its index in a block with a given
+    /// hash.
     pub fn get_txid_at_block_index(
         &self,
         block_hash: &BlockHash,
@@ -233,17 +235,20 @@ impl BlockingClient {
         self.get_opt_response(&format!("/block/{}/raw", block_hash))
     }
 
-    /// Get a merkle inclusion proof for a [`Transaction`] with the given [`Txid`].
+    /// Get a merkle inclusion proof for a [`Transaction`] with the given
+    /// [`Txid`].
     pub fn get_merkle_proof(&self, txid: &Txid) -> Result<Option<MerkleProof>, Error> {
         self.get_opt_response_json(&format!("/tx/{}/merkle-proof", txid))
     }
 
-    /// Get a [`MerkleBlock`] inclusion proof for a [`Transaction`] with the given [`Txid`].
+    /// Get a [`MerkleBlock`] inclusion proof for a [`Transaction`] with the
+    /// given [`Txid`].
     pub fn get_merkle_block(&self, txid: &Txid) -> Result<Option<MerkleBlock>, Error> {
         self.get_opt_response_hex(&format!("/tx/{}/merkleblock-proof", txid))
     }
 
-    /// Get the spending status of an output given a [`Txid`] and the output index.
+    /// Get the spending status of an output given a [`Txid`] and the output
+    /// index.
     pub fn get_output_status(
         &self,
         txid: &Txid,
@@ -299,15 +304,16 @@ impl BlockingClient {
             .map(|s| BlockHash::from_str(s.as_str()).map_err(Error::HexToArray))?
     }
 
-    /// Get an map where the key is the confirmation target (in number of blocks)
-    /// and the value is the estimated feerate (in sat/vB).
+    /// Get an map where the key is the confirmation target (in number of
+    /// blocks) and the value is the estimated feerate (in sat/vB).
     pub fn get_fee_estimates(&self) -> Result<HashMap<u16, f64>, Error> {
         self.get_response_json("/fee-estimates")
     }
 
     /// Get confirmed transaction history for the specified address/scripthash,
     /// sorted with newest first. Returns 25 transactions per page.
-    /// More can be requested by specifying the last txid seen by the previous query.
+    /// More can be requested by specifying the last txid seen by the previous
+    /// query.
     pub fn scripthash_txs(
         &self,
         script: &Script,
@@ -321,10 +327,11 @@ impl BlockingClient {
         self.get_response_json(&path)
     }
 
-    /// Gets some recent block summaries starting at the tip or at `height` if provided.
+    /// Gets some recent block summaries starting at the tip or at `height` if
+    /// provided.
     ///
-    /// The maximum number of summaries returned depends on the backend itself: esplora returns `10`
-    /// while [mempool.space](https://mempool.space/docs/api) returns `15`.
+    /// The maximum number of summaries returned depends on the backend itself:
+    /// esplora returns `10` while [mempool.space](https://mempool.space/docs/api) returns `15`.
     pub fn get_blocks(&self, height: Option<u32>) -> Result<Vec<BlockSummary>, Error> {
         let path = match height {
             Some(height) => format!("/blocks/{}", height),

src/lib.rs

@@ -41,28 +41,31 @@
 //! specific features, set `default-features` to `false` in your `Cargo.toml`
 //! and specify the features you want. This will look like this:
 //!
-//! `esplora-client = { version = "*", default-features = false, features = ["blocking"] }`
+//! `esplora-client = { version = "*", default-features = false, features =
+//! ["blocking"] }`
 //!
 //! * `blocking` enables [`minreq`], the blocking client with proxy.
-//! * `blocking-https` enables [`minreq`], the blocking client with proxy and TLS (SSL)
-//!   capabilities using the default [`minreq`] backend.
-//! * `blocking-https-rustls` enables [`minreq`], the blocking client with proxy and TLS (SSL)
-//!   capabilities using the `rustls` backend.
-//! * `blocking-https-native` enables [`minreq`], the blocking client with proxy and TLS (SSL)
-//!   capabilities using the platform's native TLS backend (likely OpenSSL).
-//! * `blocking-https-bundled` enables [`minreq`], the blocking client with proxy and TLS (SSL)
-//!   capabilities using a bundled OpenSSL library backend.
-//! * `async` enables [`reqwest`], the async client with proxy capabilities.
-//! * `async-https` enables [`reqwest`], the async client with support for proxying and TLS (SSL)
-//!   using the default [`reqwest`] TLS backend.
-//! * `async-https-native` enables [`reqwest`], the async client with support for proxying and TLS
-//!   (SSL) using the platform's native TLS backend (likely OpenSSL).
-//! * `async-https-rustls` enables [`reqwest`], the async client with support for proxying and TLS
-//!   (SSL) using the `rustls` TLS backend.
-//! * `async-https-rustls-manual-roots` enables [`reqwest`], the async client with support for
-//!   proxying and TLS (SSL) using the `rustls` TLS backend without using its the default root
-//!   certificates.
+//! * `blocking-https` enables [`minreq`], the blocking client with proxy and
+//!   TLS (SSL) capabilities using the default [`minreq`] backend.
+//! * `blocking-https-rustls` enables [`minreq`], the blocking client with proxy
+//!   and TLS (SSL) capabilities using the `rustls` backend.
+//! * `blocking-https-native` enables [`minreq`], the blocking client with proxy
+//!   and TLS (SSL) capabilities using the platform's native TLS backend (likely
+//!   OpenSSL).
+//! * `blocking-https-bundled` enables [`minreq`], the blocking client with
+//!   proxy and TLS (SSL) capabilities using a bundled OpenSSL library backend.
 //!
+//! * `async` enables [`reqwest`], the async client with proxy capabilities.
+//! * `async-https` enables [`reqwest`], the async client with support for
+//!   proxying and TLS (SSL) using the default [`reqwest`] TLS backend.
+//! * `async-https-native` enables [`reqwest`], the async client with support
+//!   for proxying and TLS (SSL) using the platform's native TLS backend (likely
+//!   OpenSSL).
+//! * `async-https-rustls` enables [`reqwest`], the async client with support
+//!   for proxying and TLS (SSL) using the `rustls` TLS backend.
+//! * `async-https-rustls-manual-roots` enables [`reqwest`], the async client
+//!   with support for proxying and TLS (SSL) using the `rustls` TLS backend
+//!   without using its the default root certificates.
 //!
 
 #![allow(clippy::result_large_err)]
@@ -71,8 +74,6 @@ use std::collections::HashMap;
 use std::fmt;
 use std::num::TryFromIntError;
 
-use bitcoin::consensus;
-
 pub mod api;
 
 #[cfg(feature = "async")]
@@ -103,21 +104,24 @@ pub fn convert_fee_rate(target: usize, estimates: HashMap<u16, f64>) -> Result<f
 
 #[derive(Debug, Clone)]
 pub struct Builder {
+    /// The URL of the Esplora server.
     pub base_url: String,
     /// Optional URL of the proxy to use to make requests to the Esplora server
     ///
-    /// The string should be formatted as: `<protocol>://<user>:<password>@host:<port>`.
+    /// The string should be formatted as:
+    /// `<protocol>://<user>:<password>@host:<port>`.
     ///
-    /// Note that the format of this value and the supported protocols change slightly between the
-    /// blocking version of the client (using `minreq`) and the async version (using `reqwest`). For more
-    /// details check with the documentation of the two crates. Both of them are compiled with
+    /// Note that the format of this value and the supported protocols change
+    /// slightly between the blocking version of the client (using `minreq`)
+    /// and the async version (using `reqwest`). For more details check with
+    /// the documentation of the two crates. Both of them are compiled with
     /// the `socks` feature enabled.
     ///
     /// The proxy is ignored when targeting `wasm32`.
     pub proxy: Option<String>,
     /// Socket timeout.
     pub timeout: Option<u64>,
-    /// HTTP headers to set on every request made to Esplora server
+    /// HTTP headers to set on every request made to Esplora server.
     pub headers: HashMap<String, String>,
 }
 
@@ -150,20 +154,20 @@ impl Builder {
         self
     }
 
-    /// build a blocking client from builder
+    /// Build a blocking client from builder
     #[cfg(feature = "blocking")]
     pub fn build_blocking(self) -> BlockingClient {
         BlockingClient::from_builder(self)
     }
 
-    // build an asynchronous client from builder
+    // Build an asynchronous client from builder
     #[cfg(feature = "async")]
     pub fn build_async(self) -> Result<AsyncClient, Error> {
         AsyncClient::from_builder(self)
     }
 }
 
-/// Errors that can happen during a sync with `Esplora`
+/// Errors that can happen during a request to `Esplora` servers.
 #[derive(Debug)]
 pub enum Error {
     /// Error during `minreq` HTTP request
@@ -186,9 +190,9 @@ pub enum Error {
     HexToBytes(bitcoin::hex::HexToBytesError),
     /// Transaction not found
     TransactionNotFound(Txid),
-    /// Header height not found
+    /// Block Header height not found
     HeaderHeightNotFound(u32),
-    /// Header hash not found
+    /// Block Header hash not found
     HeaderHashNotFound(BlockHash),
     /// Invalid HTTP Header name specified
     InvalidHttpHeaderName(String),
@@ -221,7 +225,7 @@ impl_error!(::minreq::Error, Minreq, Error);
 #[cfg(feature = "async")]
 impl_error!(::reqwest::Error, Reqwest, Error);
 impl_error!(std::num::ParseIntError, Parsing, Error);
-impl_error!(consensus::encode::Error, BitcoinEncoding, Error);
+impl_error!(bitcoin::consensus::encode::Error, BitcoinEncoding, Error);
 impl_error!(bitcoin::hex::HexToArrayError, HexToArray, Error);
 impl_error!(bitcoin::hex::HexToBytesError, HexToBytes, Error);
 
@@ -592,8 +596,8 @@ mod test {
     #[cfg(all(feature = "blocking", feature = "async"))]
     #[tokio::test]
     async fn test_get_non_existing_block_status() {
-        // Esplora returns the same status for orphaned blocks as for non-existing blocks:
-        // non-existing: https://blockstream.info/api/block/0000000000000000000000000000000000000000000000000000000000000000/status
+        // Esplora returns the same status for orphaned blocks as for non-existing
+        // blocks: non-existing: https://blockstream.info/api/block/0000000000000000000000000000000000000000000000000000000000000000/status
         // orphaned: https://blockstream.info/api/block/000000000000000000181b1a2354620f66868a723c0c4d5b24e4be8bdfc35a7f/status
         // (Here the block is cited as orphaned: https://bitcoinchain.com/block_explorer/block/000000000000000000181b1a2354620f66868a723c0c4d5b24e4be8bdfc35a7f/ )
         // For this reason, we only test for the non-existing case here.