Add warm(missing_docs), cli module docs

Author: notmandatory

src/blockchain/mod.rs

@@ -217,7 +217,7 @@ impl Progress for NoopProgress {
 #[derive(Clone)]
 pub struct LogProgress;
 
-/// Create a nwe instance of [`LogProgress`]
+/// Create a new instance of [`LogProgress`]
 pub fn log_progress() -> LogProgress {
     LogProgress
 }

src/cli.rs

@@ -22,6 +22,29 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+//! Command line interface
+//!
+//! This module provides a simple cli interface using [clap](https://docs.rs/clap/) to access
+//! basic wallet functionality. See the `repl.rs` example app for how to use this module to create
+//! a custom `bdk` based command line wallet application.
+//!
+//! # Example
+//!
+//! ```rust
+//! let app = cli::make_cli_subcommands();
+//! let app = cli::add_global_flags(app);
+//!
+//! let matches = app.get_matches();
+//!
+//! let network = match matches.value_of("network") {
+//!        Some("regtest") => Network::Regtest,
+//!        Some("testnet") | _ => Network::Testnet,
+//!     };
+//!
+//! // etc.
+//! ```
+//! See [`make_cli_subcommands()`] for list of sub-commands, and [`add_global_flags()`] for list of global flags.
+
 use std::collections::BTreeMap;
 use std::str::FromStr;
 
@@ -70,6 +93,47 @@ fn outpoint_validator(s: String) -> Result<(), String> {
     parse_outpoint(&s).map(|_| ())
 }
 
+/// Create new [clap](https://docs.rs/clap/) `App` with wallet sub-commands
+///
+/// Configuration such as name, version, author, about can be overridden. Additional sub-commands
+/// sub-commands can also be added. See [clap](https://docs.rs/clap/) for more information on how
+/// to customize an `App`.
+///
+/// # Wallet sub-commands
+///
+/// | Sub-command        | Description                                    |
+/// |--------------------|----------------------------------------------- |
+/// |  broadcast         |   Broadcasts a transaction to the network. Takes either a raw transaction or a PSBT to extract |
+/// |  bump_fee          |   Bumps the fees of an RBF transaction |
+/// |  combine_psbt      |   Combines multiple PSBTs into one |
+/// |  create_tx         |   Creates a new unsigned tranasaction |
+/// |  extract_psbt      |   Extracts a raw transaction from a PSBT |
+/// |  finalize_psbt     |   Finalizes a psbt |
+/// |  get_balance       |   Returns the current wallet balance |
+/// |  get_new_address   |   Generates a new external address |
+/// |  help              |   Prints this message or the help of the given subcommand(s) |
+/// |  list_transactions |   Lists all the incoming and outgoing transactions of the wallet |
+/// |  list_unspent      |   Lists the available spendable UTXOs |
+/// |  policies          |   Returns the available spending policies for the descriptor |
+/// |  public_descriptor |   Returns the public version of the wallet's descriptor(s) |
+/// |  repl              |   Opens an interactive shell |
+/// |  sign              |   Signs and tries to finalize a PSBT |
+/// |  sync              |   Syncs with the chosen Electrum server |
+///
+/// # Example
+///
+/// ```rust
+/// let app = cli::make_cli_subcommands();
+/// let app = app.name("Demo App")
+///              .version("0.1.0")
+///              .author("Demo Author")
+///              .about("A demo cli wallet based on the bdk library.");
+///
+/// let app = app.subcommand(
+///             SubCommand::with_name("do_something").about("Do something else with your app"),
+///         );
+/// ```
+
 pub fn make_cli_subcommands<'a, 'b>() -> App<'a, 'b> {
     App::new("Magical Bitcoin Wallet")
         .version(option_env!("CARGO_PKG_VERSION").unwrap_or("unknown"))
@@ -308,6 +372,42 @@ pub fn make_cli_subcommands<'a, 'b>() -> App<'a, 'b> {
                 )
 }
 
+/// Add [clap](https://docs.rs/clap/) global wallet options to an `App`
+///
+/// Additional app specific options can be added. See [clap](https://docs.rs/clap/) for more
+/// information on how to customize the global flags for an `App`.
+///
+/// # Wallet global flags
+///
+/// | Short | Long  | Description |
+/// |-------|-------|-------------|
+/// | -c | --change_descriptor <DESCRIPTOR>            | Sets the descriptor to use for internal addresses |
+/// | -d | --descriptor <DESCRIPTOR>                   | Sets the descriptor to use for the external addresses |
+/// | -e | --esplora <ESPLORA>                         | Use the esplora server if given as parameter |
+/// |    | --esplora_concurrency <ESPLORA_CONCURRENCY> | Concurrency of requests made to the esplora server [default: 4] |
+/// | -n | --network <NETWORK>                         | Sets the network [default: testnet]  [possible values: testnet, regtest] |
+/// | -p | --proxy <SERVER:PORT>                       | Sets the SOCKS5 proxy for the Electrum client |
+/// | -s | --server <SERVER:PORT>                      | Sets the Electrum server to use [default: ssl://electrum.blockstream.info:60002] |
+/// | -w | --wallet <WALLET_NAME>                      | Selects the wallet to use [default: main] |
+///
+/// # Example
+///
+/// ```rust
+/// let app = cli::make_cli_subcommands();
+/// let app = cli::add_global_flags(app);
+///
+/// let app = app.arg(
+///             Arg::with_name("custom")
+///                 .short("c")
+///                 .long("custom")
+///                 .value_name("CUSTOM")
+///                 .help("Sets the custom option")
+///                 .takes_value(true)
+///                 .default_value("option1")
+///                 .possible_values(&["option1", "option2"]),
+///         );
+/// ```
+
 pub fn add_global_flags<'a, 'b>(app: App<'a, 'b>) -> App<'a, 'b> {
     let mut app = app
         .arg(

src/lib.rs

@@ -22,6 +22,8 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+// rustdoc will fail if there is missing docs
+#![warn(missing_docs)]
 // only enables the `doc_cfg` feature when
 // the `docsrs` configuration attribute is defined
 #![cfg_attr(docsrs, feature(doc_cfg))]