specify exact errors in robust provider error docs

Author: 0xNeshi

src/robust_provider/provider.rs

@@ -115,7 +115,11 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
+    /// * [`Error::BlockNotFound`] - if the block with the specified hash was not found on-chain.
     pub async fn get_block_by_number(
         &self,
         number: BlockNumberOrTag,
@@ -140,7 +144,11 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
+    /// * [`Error::BlockNotFound`] - if the block with the specified hash was not found on-chain.
     pub async fn get_block(&self, id: BlockId) -> Result<N::BlockResponse, Error> {
         info!("eth_getBlock called");
         let result = self
@@ -161,7 +169,10 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
     pub async fn get_block_number(&self) -> Result<BlockNumber, Error> {
         info!("eth_getBlockNumber called");
         let result = self
@@ -187,7 +198,11 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
+    /// * [`Error::BlockNotFound`] - if the block with the specified hash was not found on-chain.
     pub async fn get_block_number_by_id(&self, block_id: BlockId) -> Result<BlockNumber, Error> {
         info!("get_block_number_by_id called");
         let result = self
@@ -214,7 +229,10 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
     pub async fn get_latest_confirmed(&self, confirmations: u64) -> Result<u64, Error> {
         info!("get_latest_confirmed called with confirmations={}", confirmations);
         let latest_block = self.get_block_number().await?;
@@ -228,7 +246,11 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
+    /// * [`Error::BlockNotFound`] - if the block with the specified hash was not found on-chain.
     pub async fn get_block_by_hash(&self, hash: BlockHash) -> Result<N::BlockResponse, Error> {
         info!("eth_getBlockByHash called");
         let result = self
@@ -250,7 +272,10 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// See [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
     pub async fn get_logs(&self, filter: &Filter) -> Result<Vec<Log>, Error> {
         info!("eth_getLogs called");
         let result = self
@@ -277,7 +302,10 @@ impl<N: Network> RobustProvider<N> {
     ///
     /// # Errors
     ///
-    /// see [retry errors](#retry-errors).
+    /// * [`Error::RpcError`] - if no fallback providers succeeded; contains the last error returned
+    ///   by the last provider attempted on the last retry.
+    /// * [`Error::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
     pub async fn subscribe_blocks(&self) -> Result<RobustSubscription<N>, Error> {
         info!("eth_subscribe called");
         let subscription = self
@@ -300,7 +328,7 @@ impl<N: Network> RobustProvider<N> {
 
     /// Execute `operation` with exponential backoff and a total timeout.
     ///
-    /// Wraps the retry logic with `tokio::time::timeout(self.call_timeout, ...)` so
+    /// Wraps the retry logic with [`tokio::time::timeout`] so
     /// the entire operation (including time spent inside the RPC call) cannot exceed
     /// `call_timeout`.
     ///
@@ -310,14 +338,11 @@ impl<N: Network> RobustProvider<N> {
     /// If `require_pubsub` is true, providers that don't support pubsub will be skipped.
     ///
     /// # Errors
-    /// <a name="retry-errors"></a>
-    ///
-    /// * Returns [`RpcError<TransportErrorKind>`] with message "total operation timeout exceeded
-    ///   and all fallback providers failed" if the overall timeout elapses and no fallback
-    ///   providers succeed.
-    /// * Returns [`RpcError::Transport(TransportErrorKind::PubsubUnavailable)`] if `require_pubsub`
-    ///   is true and all providers don't support pubsub.
-    /// * Propagates any [`RpcError<TransportErrorKind>`] from the underlying retries.
+    ///
+    /// * [`CoreError::RpcError`] - if no fallback providers succeeded; contains the last error
+    ///   returned by the last provider attempted on the last retry.
+    /// * [`CoreError::Timeout`] - if the overall operation timeout elapses (i.e. exceeds
+    ///   `call_timeout`).
     pub(crate) async fn try_operation_with_failover<T: Debug, F, Fut>(
         &self,
         operation: F,