chore(docs): minor improvements on docstrings

- apply some standard on `Cargo.toml` deps.
- minor docstring improvements, and fix missing docstrings.

Cargo.toml

@@ -19,10 +19,10 @@ 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" }
+hex = { version = "0.2", package = "hex-conservative" }
 log = "^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 }
 
 [dev-dependencies]
 serde_json = "1.0"

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

@@ -70,8 +70,6 @@ use std::collections::HashMap;
 use std::fmt;
 use std::num::TryFromIntError;
 
-use bitcoin::consensus;
-
 pub mod api;
 
 #[cfg(feature = "async")]
@@ -100,6 +98,7 @@ pub fn convert_fee_rate(target: usize, estimates: HashMap<u16, f64>) -> Option<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
     ///
@@ -116,7 +115,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>,
 }
 
@@ -149,20 +148,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
@@ -185,9 +184,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),
@@ -220,7 +219,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);