Merge #48: Improve the docs

832fe91 types: Improve README (Tobin C. Harding)
ecce5b0 doc: Update MSRV (Tobin C. Harding)
58bad5f Try to explain the odd design (Tobin C. Harding)
62a5028 doc: Add mention of jsonrpc (Tobin C. Harding)

Pull request description:

  Improve docs:

  - repo docs
  - MSRV docs
  - `types` docs

ACKs for top commit:
  apoelstra:
    ACK 832fe91; successfully ran local tests

Tree-SHA512: f07f8e5b1fb6ab1dbb86f43bd2814f330a3831bc6a626e7e4b7964a8faa9a1588692d1df59ac95dbc0caf3de188e8d87141e718e34e92aee46cf3fcdd1fb1979

README.md

@@ -28,11 +28,19 @@ integration testing.
 - `node/`: [`corepc-node`](https://crates.io/crates/corepc-node): Runs `bitcoind` regtest nodes.
 - `client/`: [`corepc-client`](https://crates.io/crates/corepc-client): A blocking JSON-RPC client used to test `corepc-types`.
 - `integration_test/`: Integration tests that use `corepc-client` and `corepc-node` to test `corepc-types`.
-
+- `jsonrpc`: [`jsonrpc`](https://crates.io/crates/jsonrpc): Rudimentary support for sending JSONRPC 2.0 requests and receiving responses.
 
 ## Design
 
-This repository is a bit oddly designed. It was done so very intentionally.
+This repository is a bit oddly designed. It was done so very intentionally. The aim is to provide
+data types for every single JSON RPC method provided by Core for many versions going back to v17.
+Furthermore we want to explicitly test every method call using every data structure to ensure we got
+it correct.
+
+Fundamentally when you make an arbitrary RPC call against a miscellaneous Bitcoin Core instance you
+do not know which version of Core you are talking to. No crate in this repository makes any effort
+to solve this problem - it is left to the application. If however you want to run a specific RPC
+call against a specific version of Core this repository is your friend.
 
 ## Original code
 

client/README.md

@@ -5,7 +5,7 @@ is only a blocking client and is intended to be used in integration testing.
 
 ## Minimum Supported Rust Version (MSRV)
 
-This library should always compile with any combination of features on **Rust 1.56.1**.
+This library should always compile with any combination of features on **Rust 1.63.0**.
 
 ## Licensing
 

node/README.md

@@ -56,20 +56,9 @@ To build docs:
 RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --features download,doc --open
 ```
 
-## MSRV
+## Minimum Supported Rust Version (MSRV)
 
-The MSRV is 1.56.1 for version 0.35.*
-
-Note: to respect 1.56.1 MSRV you need to use and older version of some dependencies, in CI the below
-dependency versions are pinned:
-
-```sh
-cargo update
-cargo update -p tempfile --precise 3.3.0
-cargo update -p log --precise 0.4.18
-```
-
-Pinning in `Cargo.toml` is avoided because it could cause compilation issues downstream.
+This library should always compile with any combination of features on **Rust 1.63.0**.
 
 ## Nix
 

types/README.md

@@ -1,10 +1,39 @@
-# corepc-types
+# Bitcoin Core JSON-RPC types
 
-Types returned by the JSON-RPC API of Bitcoin Core.
+This crate provides data types return by Bitcoin Core's JSON-RPC API. Each type is specific to the
+version of Core e.g., if you run the `getblockchaininfo` method against a Bitcoin Core v28 instance
+you will get back the data described by `types::v28::GetBlockChainInfo`. In a similar fashion any
+method `corerpcmethod` will return type `CoreRpcMethod` - snake-case as is conventional in Rust.
+
+## Status
+
+This crate is Work In Progress - not all methods for all Core versions are done yet. The single
+source of truth (SSOT) for a methods status can be found in the version specific module e.g.,
+`types/src/v17/mod.rs`. The HTML version can be found online and has nice drop down menus.
+
+See for example: https://docs.rs/corepc-types/0.5.0/corepc_types/v18/index.html
+
+### As of `v0.5.0`
+
+- All types to support `rust-miniscript` exist for Core versions 17-28 inclusive.
+- Support for Core Versions v17 and v18 is more fully fleshed out.
+- Nice docs and `verify` tool for v17 and v18 only.
+
+### Testing and Verification
+
+In order to prove the data structures we do integration testing in `integration_test`. The tests are
+version specific e.g., `cargo test --features=0_18_1`. In CI we test against all supported versions.
+If you are using this crate in CI you may want to imitate the job structure. See the `Integration`
+job in `.github/workflows/rust.yaml`.
+
+In order to back up method status our claims we provide the `verify` tool that parses the SSOT and
+checks the claims. Run it using `verify v17` (also `verify all`).
+
+The tool only currently verifies the `v17` and `v18` modules.
 
 ## Minimum Supported Rust Version (MSRV)
 
-This library should always compile with any combination of features on **Rust 1.56.1**.
+This library should always compile with any combination of features on **Rust 1.63.0**.
 
 ## Licensing