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 189a68be0654dab1453ef459d3046d5d0001c17d..0a7c655147ff0c85faf1297a2830d95b1f5746ce 100644 (file)
--- 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 6b4397a6b0fbe87d19a130fa18002a27042c9864..e1dc43c8f28d65511c45ce32591ef9eb5b933e8b 100644 (file)
--- 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());