From: Jeffrey Czyz <jkczyz@gmail.com>
Date: Fri, 3 Mar 2023 16:09:58 +0000 (-0600)
Subject: Add more documentation about BlockSourceError
X-Git-Tag: v0.0.114~3^2~1
X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=commitdiff_plain;h=8408b8d0e47b46fbec7042feb5fa16e25500c6a6;p=rust-lightning

Add more documentation about BlockSourceError

Some BlockSource implementations provide more error details. Document
this in case users want to examine it further.
---

diff --git a/lightning-block-sync/src/lib.rs b/lightning-block-sync/src/lib.rs
index 189a68be..0a7c6551 100644
--- a/lightning-block-sync/src/lib.rs
+++ b/lightning-block-sync/src/lib.rs
@@ -132,6 +132,9 @@ impl BlockSourceError {
 	}
 
 	/// Converts the error into the underlying error.
+	///
+	/// May contain an [`std::io::Error`] from the [`BlockSource`]. See implementations for further
+	/// details, if any.
 	pub fn into_inner(self) -> Box<dyn std::error::Error + Send + Sync> {
 		self.error
 	}
diff --git a/lightning-block-sync/src/rpc.rs b/lightning-block-sync/src/rpc.rs
index 6b4397a6..e1dc43c8 100644
--- a/lightning-block-sync/src/rpc.rs
+++ b/lightning-block-sync/src/rpc.rs
@@ -35,6 +35,9 @@ impl fmt::Display for RpcError {
 impl Error for RpcError {}
 
 /// A simple RPC client for calling methods using HTTP `POST`.
+///
+/// Implements [`BlockSource`] and may return an `Err` containing [`RpcError`]. See
+/// [`RpcClient::call_method`] for details.
 pub struct RpcClient {
 	basic_auth: String,
 	endpoint: HttpEndpoint,
@@ -57,6 +60,9 @@ impl RpcClient {
 	}
 
 	/// Calls a method with the response encoded in JSON format and interpreted as type `T`.
+	///
+	/// When an `Err` is returned, [`std::io::Error::into_inner`] may contain an [`RpcError`] if
+	/// [`std::io::Error::kind`] is [`std::io::ErrorKind::Other`].
 	pub async fn call_method<T>(&self, method: &str, params: &[serde_json::Value]) -> std::io::Result<T>
 	where JsonResponse: TryFrom<Vec<u8>, Error = std::io::Error> + TryInto<T, Error = std::io::Error> {
 		let host = format!("{}:{}", self.endpoint.host(), self.endpoint.port());