doc(rpc): add token/cookie auth example

Adds an example how to create an RPC client, obtain cookie-hint,
load cookie file, and call an RPC method with auth token.

fleshes out the module level doc-comments for rpc_server and rpc_auth
a bit more.

src/rpc_auth.rs

@@ -2,6 +2,12 @@
 //!
 //! These types are designed to be flexible to facilitate adding additional
 //! authentication methods in the future.
+//!
+//! (Almost) every RPC method accepts a `token` parameter which includes
+//! authentication details.
+//!
+//! At present, [Token] supports only [Cookie] based authentication.  In the
+//! future, more types will likely be added.
 use std::path::PathBuf;
 
 use rand::distributions::Alphanumeric;

src/rpc_server.rs

@@ -1,10 +1,43 @@
 //! implements an RPC server and client based on [tarpc]
 //!
-//! at present tarpc clients must also be written in rust.
+//! request and response data is json serialized.
 //!
-//! In the future we may want to explore adding an rpc layer that is friendly to
-//! other languages.
-
+//! It is presently easiest to create a tarpc client in rust.
+//! To do so, one should add neptune-cash as a dependency and
+//! then do something like:
+//!
+//! ```no_run
+//! use neptune_cash::rpc_server::RPCClient;
+//! use neptune_cash::rpc_server::rpc_auth;
+//! use tarpc::tokio_serde::formats::Json;
+//! use tarpc::serde_transport::tcp;
+//! use tarpc::client;
+//! use tarpc::context;
+//!
+//! // create a serde/json transport over tcp.
+//! let transport = tcp::connect("127.0.0.1:9799", Json::default).await.unwrap();
+//!
+//! // create an rpc client using the transport.
+//! let client = RPCClient::new(client::Config::default(), transport).spawn();
+//!
+//! // query neptune-core server how to find the cookie file
+//! let cookie_hint = client.cookie_hint(context::current()).await.unwrap().unwrap();
+//!
+//! // load the cookie file from disk and assign it to a token.
+//! let token: Token = rpc_auth::Cookie::try_load(&cookie_hint.data_directory).await.unwrap().into();
+//!
+//! // query any RPC API, passing the auth token.  here we query block_height.
+//! let block_height = client.block_height(ctx, token).await.unwrap().unwrap();
+//! ```
+//!
+//! For other languages, one would need to connect to the RPC TCP port and then
+//! manually construct the appropriate json method call.  Examples of this will
+//! be forthcoming in the future.
+//!
+//! See [rpc_auth] for descriptions of the authentication mechanisms.
+//!
+//! Every RPC method returns an [RpcResult] which is wrapped inside a
+//! [tarpc::Response] by the rpc server.
 use std::collections::HashMap;
 use std::net::IpAddr;
 use std::net::SocketAddr;
@@ -162,7 +195,7 @@ pub trait RPC {
     /******** READ DATA ********/
     // Place all methods that only read here
 
-    /// Returns a [CookieHint] for purposes of zero-conf authentication
+    /// Returns a [rpc_auth::CookieHint] for purposes of zero-conf authentication
     ///
     /// The CookieHint provides a location for the cookie file used by this
     /// neptune-core instance as well as the [Network].