Deny missing documentation

And add all the missing doc comments.

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,

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);

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<String>,
@@ -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<String>,
         scope: Option<String>,
@@ -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);
 

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<String>,
 
+        /// The npm scope to use in package.json, if any.
         #[structopt(long = "scope", short = "s")]
         scope: Option<String>,
 
@@ -43,11 +48,17 @@ pub enum Command {
 
     #[structopt(name = "pack")]
     /// 🍱  create a tar of your npm package but don't publish!
-    Pack { path: Option<String> },
+    Pack {
+        /// The path to the Rust crate.
+        path: Option<String>,
+    },
 
     #[structopt(name = "publish")]
     /// 🎆  pack up your npm package and publish!
-    Publish { path: Option<String> },
+    Publish {
+        /// The path to the Rust crate.
+        path: Option<String>,
+    },
 
     #[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

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>) -> String {
     let crate_path = match path {
         Some(p) => p,

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("🎯  ", "");

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<str>) -> 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",

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,

src/logger.rs

@@ -1,3 +1,5 @@
+//! Logging facilities for `wasm-pack`.
+
 use command::Command;
 use error::Error;
 use slog::{Drain, Level, Logger};

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<String, Error> {
     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);

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<String>,

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<ProgressBar>,
     messages: RwLock<String>,
 }
 
 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;
     }

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);