Add some docs for RpcClient and friends (backport #18748) (#19036)

* Add some docs for RpcClient and friends (#18748)

* Add some docs for RpcSender, HttpSender, MockSender

* Support SimulateTransaction in MockSender

* Add docs for RpcClient constructors

* Add some more RpcClient examples

* rustfmt

* Reflow docs in rpc_client and friends

(cherry picked from commit 5dcfd7c)

# Conflicts:
#	client/src/mock_sender.rs

* Fix conflicts

Co-authored-by: Brian Anderson <andersrb@gmail.com>
Co-authored-by: Tyera Eulberg <tyera@solana.com>

client/src/http_sender.rs

@@ -1,3 +1,5 @@
+//! The standard [`RpcSender`] over HTTP.
+
 use {
     crate::{
         client_error::Result,
@@ -28,11 +30,19 @@ pub struct HttpSender {
     request_id: AtomicU64,
 }
 
+/// The standard [`RpcSender`] over HTTP.
 impl HttpSender {
+    /// Create an HTTP RPC sender.
+    ///
+    /// The URL is an HTTP URL, usually for port 8899, as in
+    /// "http://localhost:8899". The sender has a default timeout of 30 seconds.
     pub fn new(url: String) -> Self {
         Self::new_with_timeout(url, Duration::from_secs(30))
     }
 
+    /// Create an HTTP RPC sender.
+    ///
+    /// The URL is an HTTP URL, usually for port 8899.
     pub fn new_with_timeout(url: String, timeout: Duration) -> Self {
         // `reqwest::blocking::Client` panics if run in a tokio async context.  Shuttle the
         // request to a different tokio thread to avoid this

client/src/mock_sender.rs

@@ -1,10 +1,12 @@
+//! An [`RpcSender`] used for unit testing [`RpcClient`](crate::rpc_client::RpcClient).
+
 use {
     crate::{
         client_error::Result,
         rpc_request::RpcRequest,
         rpc_response::{
             Response, RpcBlockProduction, RpcBlockProductionRange, RpcResponseContext,
-            RpcVersionInfo,
+            RpcSimulateTransactionResult, RpcVersionInfo,
         },
         rpc_sender::RpcSender,
     },
@@ -31,6 +33,31 @@ pub struct MockSender {
     url: String,
 }
 
+/// An [`RpcSender`] used for unit testing [`RpcClient`](crate::rpc_client::RpcClient).
+///
+/// This is primarily for internal use.
+///
+/// Unless directed otherwise, it will generally return a reasonable default
+/// response, at least for [`RpcRequest`] values for which responses have been
+/// implemented.
+///
+/// The behavior can be customized in two ways:
+///
+/// 1) The `url` constructor argument is not actually a URL, but a simple string
+///    directive that changes `MockSender`s behavior in specific scenarios.
+///
+///    If `url` is "fails" then any call to `send` will return `Ok(Value::Null)`.
+///
+///    It is customary to set the `url` to "succeeds" for mocks that should
+///    return sucessfully, though this value is not actually interpreted.
+///
+///    Other possible values of `url` are specific to different `RpcRequest`
+///    values. Read the implementation for specifics.
+///
+/// 2) Custom responses can be configured by providing [`Mocks`] to the
+///    [`MockSender::new_with_mocks`] constructor. This type is a [`HashMap`]
+///    from [`RpcRequest`] to a JSON [`Value`] response, Any entries in this map
+///    override the default behavior for the given request.
 impl MockSender {
     pub fn new(url: String) -> Self {
         Self::new_with_mocks(url, Mocks::default())
@@ -143,6 +170,14 @@ impl RpcSender for MockSender {
                 };
                 Value::String(signature)
             }
+            "simulateTransaction" => serde_json::to_value(Response {
+                context: RpcResponseContext { slot: 1 },
+                value: RpcSimulateTransactionResult {
+                    err: None,
+                    logs: None,
+                    accounts: None,
+                },
+            })?,
             "getMinimumBalanceForRentExemption" => json![20],
             "getVersion" => {
                 let version = Version::default();