Add documentation

Add documentation for the library,
the blocking client and the non-blocking
client.

Author: vladimirfomene

src/async.rs

@@ -32,6 +32,7 @@ pub struct AsyncClient {
 }
 
 impl AsyncClient {
+    /// build an async client from a builder
     pub fn from_builder(builder: Builder) -> Result<Self, Error> {
         let mut client_builder = Client::builder();
 
@@ -48,10 +49,12 @@ impl AsyncClient {
         Ok(Self::from_client(builder.base_url, client_builder.build()?))
     }
 
+    /// build an async client from the base url and [`Client`]
     pub fn from_client(url: String, client: Client) -> Self {
         AsyncClient { url, client }
     }
 
+    /// Get a [`Transaction`] option given its [`Txid`]
     pub async fn get_tx(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
         let resp = self
             .client
@@ -66,6 +69,7 @@ impl AsyncClient {
         Ok(Some(deserialize(&resp.error_for_status()?.bytes().await?)?))
     }
 
+    /// Get a [`Transaction`] given its [`Txid`]
     pub async fn get_tx_no_opt(&self, txid: &Txid) -> Result<Transaction, Error> {
         match self.get_tx(txid).await {
             Ok(Some(tx)) => Ok(tx),
@@ -74,6 +78,7 @@ impl AsyncClient {
         }
     }
 
+    /// Get a [`BlockHeader`] given a particular block height.
     pub async fn get_header(&self, block_height: u32) -> Result<BlockHeader, Error> {
         let resp = self
             .client
@@ -99,6 +104,7 @@ impl AsyncClient {
         Ok(header)
     }
 
+    /// Broadcast a [`Transaction`] to Esplora
     pub async fn broadcast(&self, transaction: &Transaction) -> Result<(), Error> {
         self.client
             .post(&format!("{}/tx", self.url))
@@ -110,6 +116,7 @@ impl AsyncClient {
         Ok(())
     }
 
+    /// Get the current height of the blockchain tip
     pub async fn get_height(&self) -> Result<u32, Error> {
         let req = self
             .client
@@ -120,6 +127,9 @@ impl AsyncClient {
         Ok(req.error_for_status()?.text().await?.parse()?)
     }
 
+    /// 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.
     pub async fn scripthash_txs(
         &self,
         script: &Script,
@@ -143,6 +153,8 @@ impl AsyncClient {
             .await?)
     }
 
+    /// 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<String, f64>, Error> {
         Ok(self
             .client

src/blocking.rs

@@ -35,6 +35,7 @@ pub struct BlockingClient {
 }
 
 impl BlockingClient {
+    /// build a blocking client from a [`Builder`]
     pub fn from_builder(builder: Builder) -> Result<Self, Error> {
         let mut agent_builder = ureq::AgentBuilder::new();
 
@@ -49,10 +50,12 @@ impl BlockingClient {
         Ok(Self::from_agent(builder.base_url, agent_builder.build()))
     }
 
+    /// build a blocking client from an [`Agent`]
     pub fn from_agent(url: String, agent: Agent) -> Self {
         BlockingClient { url, agent }
     }
 
+    /// Get a [`Transaction`] option given its [`Txid`]
     pub fn get_tx(&self, txid: &Txid) -> Result<Option<Transaction>, Error> {
         let resp = self
             .agent
@@ -71,6 +74,7 @@ impl BlockingClient {
         }
     }
 
+    /// Get a [`Transaction`] given its [`Txid`]
     pub fn get_tx_no_opt(&self, txid: &Txid) -> Result<Transaction, Error> {
         match self.get_tx(txid) {
             Ok(Some(tx)) => Ok(tx),
@@ -79,6 +83,7 @@ impl BlockingClient {
         }
     }
 
+    /// Get a [`BlockHeader`] given a particular block height.
     pub fn get_header(&self, block_height: u32) -> Result<BlockHeader, Error> {
         let resp = self
             .agent
@@ -106,6 +111,7 @@ impl BlockingClient {
         }
     }
 
+    /// Broadcast a [`Transaction`] to Esplora
     pub fn broadcast(&self, transaction: &Transaction) -> Result<(), Error> {
         let resp = self
             .agent
@@ -119,6 +125,7 @@ impl BlockingClient {
         }
     }
 
+    /// Get the current height of the blockchain tip
     pub fn get_height(&self) -> Result<u32, Error> {
         let resp = self
             .agent
@@ -132,6 +139,8 @@ impl BlockingClient {
         }
     }
 
+    /// 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<String, f64>, Error> {
         let resp = self
             .agent
@@ -150,6 +159,9 @@ impl BlockingClient {
         Ok(map)
     }
 
+    /// 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.
     pub fn scripthash_txs(
         &self,
         script: &Script,

src/lib.rs

@@ -1,29 +1,47 @@
-//! Esplora
+//! An extensible blocking/async Esplora client
 //!
-//! This module defines a [`Builder`] struct that can create a blocking or
-//! async Esplora client to query an Esplora backend:
+//! This library provides an extensible blocking and
+//! async Esplora client to query Esplora's backend.
 //!
-//! ## Examples
+//! The library provides the possibility to build a blocking
+//! client using [`ureq`] and an async client using [`reqwest`].
+//! The library supports communicating to Esplora via a proxy
+//! and also using TLS (SSL) for secure communication.
+//!
+//!
+//! ## Usage
+//!
+//! You can create a blocking client as follows:
 //!
 //! ```no_run
-//! # use esplora_client::Builder;
+//! use esplora_client::Builder;
 //! let builder = Builder::new("https://blockstream.info/testnet/api");
 //! let blocking_client = builder.build_blocking();
 //! # Ok::<(), esplora_client::Error>(());
 //! ```
+//!
+//! Here is an example of how to create an asynchronous client.
+//!
 //! ```no_run
-//! # use esplora_client::Builder;
+//! use esplora_client::Builder;
 //! let builder = Builder::new("https://blockstream.info/testnet/api");
 //! let async_client = builder.build_async();
 //! # Ok::<(), esplora_client::Error>(());
 //! ```
 //!
-//! Esplora client can use either `ureq` or `reqwest` for the HTTP client
-//! depending on your needs (blocking or async respectively).
+//! ## Features
+//!
+//! By default the library enables all features. To specify
+//! 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"] }`
+//!
+//! * `blocking` enables [`ureq`], the blocking client with proxy and TLS (SSL) capabilities.
+//! * `async` enables [`reqwest`], the async client with proxy capabilities.
+//! * `async-https` enables [`reqwest`], the async client with support for proxying and TLS (SSL).
+//!
 //!
-//! Please note, to configure the Esplora HTTP client correctly use one of:
-//! Blocking:  --features='blocking'
-//! Async:     --features='async'
 use std::collections::HashMap;
 use std::fmt;
 use std::io;
@@ -44,6 +62,8 @@ pub use blocking::BlockingClient;
 #[cfg(any(feature = "async", feature = "async-https"))]
 pub use r#async::AsyncClient;
 
+/// Get a fee value in sats/vbytes from the estimates
+/// that matches the confirmation target set as parameter.
 pub fn convert_fee_rate(target: usize, estimates: HashMap<String, f64>) -> Result<f32, Error> {
     let fee_val = {
         let mut pairs = estimates
@@ -79,6 +99,7 @@ pub struct Builder {
 }
 
 impl Builder {
+    /// Instantiate a new builder
     pub fn new(base_url: &str) -> Self {
         Builder {
             base_url: base_url.to_string(),
@@ -87,28 +108,32 @@ impl Builder {
         }
     }
 
+    /// Set the proxy of the builder
     pub fn proxy(mut self, proxy: &str) -> Self {
         self.proxy = Some(proxy.to_string());
         self
     }
 
+    /// Set the timeout of the builder
     pub fn timeout(mut self, timeout: u64) -> Self {
         self.timeout = Some(timeout);
         self
     }
 
+    /// build a blocking client from builder
     #[cfg(feature = "blocking")]
     pub fn build_blocking(self) -> Result<BlockingClient, Error> {
         BlockingClient::from_builder(self)
     }
 
+    // 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 [`EsploraBlockchain`]
+/// Errors that can happen during a sync with `Esplora`
 #[derive(Debug)]
 pub enum Error {
     /// Error during ureq HTTP request