diff --git a/src/bindgen.rs b/src/bindgen.rs index dece43f..61d9ac1 100644 --- a/src/bindgen.rs +++ b/src/bindgen.rs @@ -1,9 +1,12 @@ +//! Functionality related to installing and running `wasm-bindgen`. + use emoji; use error::Error; use progressbar::Step; use std::process::Command; use PBAR; +/// Install the `wasm-bindgen` CLI with `cargo install`. pub fn cargo_install_wasm_bindgen(step: &Step) -> Result<(), Error> { let msg = format!("{}Installing WASM-bindgen...", emoji::DOWN_ARROW); PBAR.step(step, &msg); @@ -24,6 +27,8 @@ pub fn cargo_install_wasm_bindgen(step: &Step) -> Result<(), Error> { } } +/// Run the `wasm-bindgen` CLI to generate bindings for the current crate's +/// `.wasm`. pub fn wasm_bindgen_build( path: &str, name: &str, diff --git a/src/build.rs b/src/build.rs index 61d02d2..1744f99 100644 --- a/src/build.rs +++ b/src/build.rs @@ -1,9 +1,13 @@ +//! Building a Rust crate into a `.wasm` binary. + use emoji; use error::Error; use progressbar::Step; use std::process::Command; use PBAR; +/// Ensure that `rustup` has the `wasm32-unknown-unknown` target installed for +/// the `nightly` toolchain. pub fn rustup_add_wasm_target(step: &Step) -> Result<(), Error> { let msg = format!("{}Adding WASM target...", emoji::TARGET); PBAR.step(step, &msg); @@ -23,6 +27,7 @@ pub fn rustup_add_wasm_target(step: &Step) -> Result<(), Error> { } } +/// Ensure that the `nightly` toolchain is installed in `rustup`. fn ensure_nightly() -> Result<(), Error> { let nightly_check = Command::new("rustc").arg("+nightly").arg("-V").output()?; if !nightly_check.status.success() { @@ -39,6 +44,8 @@ fn ensure_nightly() -> Result<(), Error> { Ok(()) } +/// Run `cargo build` with the `nightly` toolchain and targetting +/// `wasm32-unknown-unknown`. pub fn cargo_build_wasm(path: &str, debug: bool, step: &Step) -> Result<(), Error> { let msg = format!("{}Compiling to WASM...", emoji::CYCLONE); PBAR.step(step, &msg); diff --git a/src/command/init.rs b/src/command/init.rs index d35cf95..bec96f8 100644 --- a/src/command/init.rs +++ b/src/command/init.rs @@ -1,3 +1,5 @@ +//! Initializing a crate for packing `.wasm`s. + use bindgen; use build; use command::utils::set_crate_path; @@ -12,6 +14,7 @@ use std::fs; use std::time::Instant; use PBAR; +/// Construct our `pkg` directory in the crate. pub fn create_pkg_dir(path: &str, step: &Step) -> Result<(), Error> { let msg = format!("{}Creating a pkg directory...", emoji::FOLDER); PBAR.step(step, &msg); @@ -20,12 +23,20 @@ pub fn create_pkg_dir(path: &str, step: &Step) -> Result<(), Error> { Ok(()) } +/// The `InitMode` determines which mode of initialization we are running, and +/// what build and install steps we perform. pub enum InitMode { + /// Perform all the build and install steps. Normal, + /// Don't build the crate as a `.wasm` but do install tools and create + /// meta-data. Nobuild, + /// Don't install tools like `wasm-bindgen`, just use the global + /// environment's existing versions to do builds. Noinstall, } +/// Everything required to configure and run the `wasm-pack init` command. pub struct Init { crate_path: String, scope: Option, @@ -38,6 +49,7 @@ pub struct Init { type InitStep = fn(&mut Init, &Step, &Logger) -> Result<(), Error>; impl Init { + /// Construct a new `Init` command. pub fn new( path: Option, scope: Option, @@ -92,6 +104,7 @@ impl Init { } } + /// Execute this `Init` command. pub fn process(&mut self, log: &Logger, mode: InitMode) -> Result<(), Error> { let process_steps = Init::get_process_steps(mode); diff --git a/src/command/mod.rs b/src/command/mod.rs index d3c9b7e..2f477b9 100644 --- a/src/command/mod.rs +++ b/src/command/mod.rs @@ -1,3 +1,5 @@ +//! CLI command structures, parsing, and execution. + pub mod init; mod login; mod pack; @@ -13,13 +15,16 @@ use slog::Logger; use std::result; use PBAR; +/// The various kinds of commands that `wasm-pack` can execute. #[derive(Debug, StructOpt)] pub enum Command { #[structopt(name = "init")] /// 🐣 initialize a package.json based on your compiled wasm! Init { + /// The path to the Rust crate. path: Option, + /// The npm scope to use in package.json, if any. #[structopt(long = "scope", short = "s")] scope: Option, @@ -43,11 +48,17 @@ pub enum Command { #[structopt(name = "pack")] /// 🍱 create a tar of your npm package but don't publish! - Pack { path: Option }, + Pack { + /// The path to the Rust crate. + path: Option, + }, #[structopt(name = "publish")] /// 🎆 pack up your npm package and publish! - Publish { path: Option }, + Publish { + /// The path to the Rust crate. + path: Option, + }, #[structopt(name = "login", alias = "adduser", alias = "add-user")] /// 👤 Add a registry user account! (aliases: adduser, add-user) @@ -82,6 +93,7 @@ pub enum Command { }, } +/// Run a command with the given logger! pub fn run_wasm_pack(command: Command, log: &Logger) -> result::Result<(), Error> { // Run the correct command based off input and store the result of it so that we can clear // the progress bar then return it diff --git a/src/command/utils.rs b/src/command/utils.rs index ff85ef0..9269534 100644 --- a/src/command/utils.rs +++ b/src/command/utils.rs @@ -1,3 +1,7 @@ +//! Utility functions for commands. + +/// If an explicit path is given, then use it, otherwise assume the current +/// directory is the crate path. pub fn set_crate_path(path: Option) -> String { let crate_path = match path { Some(p) => p, diff --git a/src/emoji.rs b/src/emoji.rs index e93119c..8a7bc8d 100644 --- a/src/emoji.rs +++ b/src/emoji.rs @@ -1,3 +1,16 @@ +//! Emoji contants used by `wasm-pack`. +//! +//! For the woefully unfamiliar: +//! +//! > Emoji are ideograms and smileys used in electronic messages and web +//! > pages. Emoji exist in various genres, including facial expressions, common +//! > objects, places and types of weather, and animals. They are much like +//! > emoticons, but emoji are actual pictures instead of typographics. +//! +//! -- https://en.wikipedia.org/wiki/Emoji + +#![allow(missing_docs)] + use console::Emoji; pub static TARGET: Emoji = Emoji("🎯 ", ""); diff --git a/src/error.rs b/src/error.rs index 0bd2ba6..1d6f0a7 100644 --- a/src/error.rs +++ b/src/error.rs @@ -4,22 +4,40 @@ use std::borrow::Cow; use std::io; use toml; +/// Errors that can potentially occur in `wasm-pack`. #[derive(Debug, Fail)] pub enum Error { /// Maps any underlying I/O errors that are thrown to this variant #[fail(display = "{}", _0)] Io(#[cause] io::Error), + + /// A JSON serialization or deserialization error. #[fail(display = "{}", _0)] SerdeJson(#[cause] serde_json::Error), + + /// A TOML serialization or deserialization error. #[fail(display = "{}", _0)] SerdeToml(#[cause] toml::de::Error), + + /// An error invoking another CLI tool. #[fail(display = "{}. stderr:\n\n{}", message, stderr)] - Cli { message: String, stderr: String }, + Cli { + /// Error message. + message: String, + /// The underlying CLI's `stderr` output. + stderr: String, + }, + + /// A crate configuration error. #[fail(display = "{}", message)] - CrateConfig { message: String }, + CrateConfig { + /// A message describing the configuration error. + message: String, + }, } impl Error { + /// Construct a CLI error. pub fn cli(message: &str, stderr: Cow) -> Result<(), Self> { Err(Error::Cli { message: message.to_string(), @@ -27,12 +45,14 @@ impl Error { }) } + /// Construct a crate configuration error. pub fn crate_config(message: &str) -> Result<(), Self> { Err(Error::CrateConfig { message: message.to_string(), }) } + /// Get a string description of this error's type. pub fn error_type(&self) -> String { match self { Error::Io(_) => "There was an I/O error. Details:\n\n", diff --git a/src/lib.rs b/src/lib.rs index 7b510b0..1c31bd8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,7 @@ +//! Your favorite rust -> wasm workflow tool! + +#![deny(missing_docs)] + extern crate console; #[macro_use] extern crate failure; @@ -30,14 +34,17 @@ pub mod readme; use progressbar::ProgressOutput; lazy_static! { + /// The global progress bar and user-facing message output. pub static ref PBAR: ProgressOutput = { ProgressOutput::new() }; } /// 📦 ✨ pack and publish your wasm! #[derive(Debug, StructOpt)] pub struct Cli { + /// The subcommand to run. #[structopt(subcommand)] // Note that we mark a field as a subcommand pub cmd: command::Command, + /// Log verbosity is based off the number of v used #[structopt(long = "verbose", short = "v", parse(from_occurrences))] pub verbosity: u8, diff --git a/src/logger.rs b/src/logger.rs index fc7e7f4..3ddea3a 100644 --- a/src/logger.rs +++ b/src/logger.rs @@ -1,3 +1,5 @@ +//! Logging facilities for `wasm-pack`. + use command::Command; use error::Error; use slog::{Drain, Level, Logger}; diff --git a/src/manifest.rs b/src/manifest.rs index e545a1a..a6628c6 100644 --- a/src/manifest.rs +++ b/src/manifest.rs @@ -1,3 +1,5 @@ +//! Reading and writing Cargo.toml and package.json manifests. + use std::fs::File; use std::io::prelude::*; @@ -159,10 +161,12 @@ pub fn write_package_json( Ok(()) } +/// Get the crate name for the crate at the given path. pub fn get_crate_name(path: &str) -> Result { Ok(read_cargo_toml(path)?.package.name) } +/// Check that the crate the given path is properly configured. pub fn check_crate_config(path: &str, step: &Step) -> Result<(), Error> { let msg = format!("{}Checking crate configuration...", emoji::WRENCH); PBAR.step(&step, &msg); diff --git a/src/npm.rs b/src/npm.rs index 3ea414d..befcdd6 100644 --- a/src/npm.rs +++ b/src/npm.rs @@ -1,8 +1,12 @@ +//! Functionality related to publishing to npm. + use error::Error; use std::process::{Command, Stdio}; +/// The default npm registry used when we aren't working with a custom registry. pub const DEFAULT_NPM_REGISTRY: &'static str = "https://registry.npmjs.org/"; +/// Run the `npm pack` command. pub fn npm_pack(path: &str) -> Result<(), Error> { let pkg_file_path = format!("{}/pkg", path); let output = Command::new("npm") @@ -17,6 +21,7 @@ pub fn npm_pack(path: &str) -> Result<(), Error> { } } +/// Run the `npm publish` command. pub fn npm_publish(path: &str) -> Result<(), Error> { let pkg_file_path = format!("{}/pkg", path); let output = Command::new("npm") @@ -31,6 +36,7 @@ pub fn npm_publish(path: &str) -> Result<(), Error> { } } +/// Run the `npm login` command. pub fn npm_login( registry: &String, scope: &Option, diff --git a/src/progressbar.rs b/src/progressbar.rs index f2b070c..24a8947 100644 --- a/src/progressbar.rs +++ b/src/progressbar.rs @@ -1,15 +1,19 @@ +//! Fancy progress bar functionality. + use console::style; use emoji; use indicatif::{ProgressBar, ProgressStyle}; use parking_lot::RwLock; use std::fmt; +/// Synchronized progress bar and status message printing. pub struct ProgressOutput { spinner: RwLock, messages: RwLock, } impl ProgressOutput { + /// Construct a new `ProgressOutput`. pub fn new() -> Self { Self { spinner: RwLock::new(ProgressBar::new_spinner()), @@ -17,6 +21,8 @@ impl ProgressOutput { } } + /// Inform the user that the given `step` is being executed, with details in + /// `message`. pub fn step(&self, step: &Step, message: &str) { let msg = format!("{} {}", style(step).bold().dim(), message); self.message(&msg) @@ -31,6 +37,7 @@ impl ProgressOutput { message.clear(); } + /// Print the given message. pub fn message(&self, message: &str) { self.finish(); @@ -45,6 +52,7 @@ impl ProgressOutput { message.push('\n'); } + /// Add an informational message. pub fn info(&self, message: &str) { let info = format!( "{} {}: {}", @@ -55,6 +63,7 @@ impl ProgressOutput { self.add_message(&info); } + /// Add a warning message. pub fn warn(&self, message: &str) { let warn = format!( "{} {}: {}", @@ -65,6 +74,7 @@ impl ProgressOutput { self.add_message(&warn); } + /// Add an error message. pub fn error(&self, message: String) { let err = format!( "{} {}: {}", @@ -87,20 +97,28 @@ impl ProgressOutput { pb } + /// After having built up a series of messages, print all of them out. pub fn done(&self) { self.finish(); } } +/// For processes that can be broken down into N fractional steps, with messages +/// added for each step along the way like +/// +/// > [2/5] Doing the second step out of five. pub struct Step { current: usize, total: usize, } impl Step { + /// Construct a `Step` where there are `total` number of steps. pub fn new(total: usize) -> Step { Step { current: 1, total } } + + /// Increment the current step. pub fn inc(&mut self) { self.current += 1; } diff --git a/src/readme.rs b/src/readme.rs index 041908a..5f631e0 100644 --- a/src/readme.rs +++ b/src/readme.rs @@ -1,3 +1,5 @@ +//! Generating `README` files for the packaged wasm. + use error::Error; use std::fs; @@ -5,6 +7,7 @@ use emoji; use progressbar::Step; use PBAR; +/// Copy the crate's README into the `pkg` directory. pub fn copy_from_crate(path: &str, step: &Step) -> Result<(), Error> { let msg = format!("{}Copying over your README...", emoji::DANCERS); PBAR.step(step, &msg);