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

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 }
     }

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,

src/lib.rs

@@ -52,6 +52,7 @@
 //!   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.
@@ -71,8 +72,6 @@ use std::collections::HashMap;
 use std::fmt;
 use std::num::TryFromIntError;
 
-use bitcoin::consensus;
-
 pub mod api;
 
 #[cfg(feature = "async")]
@@ -103,6 +102,7 @@ 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
     ///
@@ -117,7 +117,7 @@ pub struct Builder {
     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 +150,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 +186,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 +221,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);