Merge pull request #208 from fitzgen/deny-missing-docs

Deny missing documentation

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,35 +4,55 @@ 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(),
             stderr: stderr.to_string(),
         })
     }
 
+    /// 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>,