Merge pull request #56 from chainwayxyz/documentation

Documentation improvements

Author: ceyhunsen

README.md

@@ -29,7 +29,7 @@ fn my_func() {
     let strct = MyStruct {
         data: 0x45,
         // This will connect to Bitcoin RPC.
-        rpc: bitcoincore_rpc::Client::new(/** parameters here **/),
+        rpc: bitcoincore_rpc::Client::new("127.0.0.1", bitcoincore_rpc::Auth::None).unwrap(),
     };
 
     // Do stuff...
@@ -40,7 +40,7 @@ fn test() {
     let strct = MyStruct {
         data: 0x1F,
         // This will connect to mock RPC.
-        rpc: bitcoin_mock_rpc::Client::new(/** parameters here **/),
+        rpc: bitcoin_mock_rpc::Client::new("db_name", bitcoincore_rpc::Auth::None).unwrap(),
     };
 
     // Do stuff...

src/lib.rs

@@ -1,10 +1,69 @@
 //! # Bitcoin Mock Remote Procedure Call
 //!
-//! This library mocks [bitcoincore-rpc](https://github.com/rust-bitcoin/rust-bitcoincore-rpc)
+//! bitcoin-mock-rpc is an RPC library, that builds on a mock Bitcoin ledger and
+//! without a wallet or consenses implementation. It aims to provide an easier
+//! way to check your Bitcoin operations without you needing to setup a Bitcoin
+//! environment.
+//!
+//! This library mocks
+//! [bitcoincore-rpc](https://github.com/rust-bitcoin/rust-bitcoincore-rpc)
 //! library. This mock takes advantage of `RpcApi` trait.
 //!
-//! Applications can implement another trait that will switch between this mock
-//! and the real RPC interface, for tests and production respectively.
+//! ## Interface
+//!
+//! ```text
+//! ┌────────────────────┐
+//! │                    │
+//! │  User Application  │
+//! │                    │
+//! └────────▲───────────┘
+//!          │
+//!  ┌───────┴────────┐
+//!  │                │
+//!  │  RpcApi Trait  │
+//!  │   Interface    │
+//!  │                │
+//!  └───────▲────────┘
+//!          │
+//!  ┌───────┴─────┐
+//!  │             │
+//!  │ Mock Ledger │
+//!  │             │
+//!  └─────────────┴
+//! ```
+//!
+//! `RpcApiWrapper` trait can be used to select between real and mock RPC. It is
+//! a simple wrapper that allows you to also use methods like `Client::new()`.
+//! Needs changes in your code:
+//!
+//! ```rust
+//! use bitcoin_mock_rpc::RpcApiWrapper;
+//!
+//! struct MyStruct<R: RpcApiWrapper> {
+//!     data: u32,
+//!     rpc: R,
+//! }
+//!
+//! fn my_func() {
+//!     let strct = MyStruct {
+//!         data: 0x45,
+//!         // This will connect to Bitcoin RPC.
+//!         rpc: bitcoincore_rpc::Client::new("127.0.0.1", bitcoincore_rpc::Auth::None).unwrap(),
+//!     };
+//!
+//!     // Do stuff...
+//! }
+//!
+//! fn test() {
+//!     let strct = MyStruct {
+//!         data: 0x1F,
+//!         // This will connect to mock RPC.
+//!         rpc: bitcoin_mock_rpc::Client::new("db_name", bitcoincore_rpc::Auth::None).unwrap(),
+//!     };
+//!
+//!     // Do stuff...
+//! }
+//! ```
 
 pub mod client;
 mod ledger;
@@ -15,3 +74,5 @@ pub use client::*;
 
 #[cfg(feature = "rpc_server")]
 pub mod rpc;
+#[cfg(feature = "rpc_server")]
+pub use rpc::*;

src/rpc/mod.rs

@@ -2,6 +2,10 @@
 //!
 //! This crate provides an RPC server that will act like the real Bitcoin RPC
 //! interface.
+//!
+//! WARNING: This crate is not actively maintained. And won't work correctly.
+//! There is so much work needs to be done in this crate. Use it in your own
+//! risk. `--features rpc_server` can be used to enable this crate.
 
 use crate::{Client, RpcApiWrapper};
 use jsonrpsee::server::middleware::rpc::RpcServiceT;