Add doc comments to public types, functions, and modules

src/active_copirate.rs

@@ -1,3 +1,5 @@
+//! Records the currently active co-authors collaborating on this Git repository.
+
 use std::fs::{self, File, OpenOptions};
 use std::io::Write;
 use std::path::Path;
@@ -7,17 +9,22 @@ use crate::BoxResult;
 
 const ACTIVE_COPIRATES_PATH: &str = ".git/.git-rmob-template";
 
+/// File containing `Co-authored-by` lines for all active co-authors.
 #[derive(Debug)]
 pub struct ActiveCoPirates {
     file: File,
 }
 
 impl ActiveCoPirates {
+    /// Opens a pre-existing co-pirates file for the repository located at `repo_dir`.
     pub fn get(repo_dir: &Path) -> BoxResult<String> {
         let active_copirates = fs::read_to_string(repo_dir.join(ACTIVE_COPIRATES_PATH))?;
         Ok(active_copirates)
     }
 
+    /// Creates an empty active co-pirates file for the repository located at `repo_dir`.
+    ///
+    /// If the file already exists, its contents will be cleared.
     pub fn create_empty(repo_dir: &Path) -> BoxResult<ActiveCoPirates> {
         let active_copirates_path = repo_dir.join(ACTIVE_COPIRATES_PATH);
         fs::write(&active_copirates_path, "")?;
@@ -29,6 +36,7 @@ impl ActiveCoPirates {
         Ok(ActiveCoPirates { file })
     }
 
+    /// Generates `Co-authored-by` messages for the given co-pirates and saves the file to disk.
     pub fn save(mut self, copirates: &[&CoPirate]) -> BoxResult<()> {
         for pirate in copirates {
             writeln!(self.file, "Co-authored-by: {}", pirate)?;

src/copirate.rs

@@ -1,3 +1,5 @@
+//! Configuration for all known co-author names and emails.
+
 use std::collections::HashMap;
 use std::fmt::{Display, Formatter, Result as FmtResult};
 use std::fs;
@@ -7,6 +9,7 @@ use serde::Deserialize;
 
 use crate::BoxResult;
 
+/// Represents the details of a single co-author.
 #[derive(Debug, Deserialize, Eq, PartialEq)]
 pub struct CoPirate {
     pub name: String,
@@ -19,18 +22,21 @@ impl Display for CoPirate {
     }
 }
 
+/// Configuration file which assigns convenient two-letter aliases to co-authors.
 #[derive(Debug, Deserialize, Eq, PartialEq)]
 pub struct CoPirates {
     copirates: HashMap<String, CoPirate>,
 }
 
 impl CoPirates {
+    /// Parses the given co-authors file as JSON.
     pub fn open(copirates_path: &Path) -> BoxResult<CoPirates> {
         let raw_copirates = fs::read_to_string(copirates_path)?;
         let existing_copirates = serde_json::from_str(&raw_copirates)?;
         Ok(existing_copirates)
     }
 
+    /// Returns the details of the given co-author, if known.
     pub fn get(&self, copirate: &String) -> BoxResult<&CoPirate> {
         let copirate = self.copirates.get(copirate).ok_or("Shiver me timbers! This be pirate be a stranger around these ports. Hint: Add it to ~/.git-copirates!")?;
         Ok(copirate)

src/embark.rs

@@ -1,11 +1,12 @@
-//! embark sub-command
+//! Subcommand for initializing `rmob` with the given Git repository.
 
 use std::os::unix::fs::OpenOptionsExt;
 use std::path::Path;
 use std::{fs, io::Result as IoResult};
 
 use crate::{BoxResult, HOOK_PATH};
 
+/// Registers the `rmob` Git hook with the Git repository located at `repo_dir`.
 pub fn embark(repo_dir: &Path) -> BoxResult<()> {
     let hook_path = repo_dir.join(HOOK_PATH);
     if hook_path.exists() {
@@ -17,6 +18,7 @@ pub fn embark(repo_dir: &Path) -> BoxResult<()> {
     Ok(())
 }
 
+/// Writes an executable Git hook script to the location at `hook_file`.
 pub fn create_hook(hook_file: &Path) -> IoResult<()> {
     let hook_code = "#!/bin/bash
 

src/lib.rs

@@ -1,3 +1,5 @@
+//! Command for including co-authors in Git commits when collaborating on code.
+
 use std::error::Error;
 use std::path::PathBuf;
 
@@ -36,6 +38,7 @@ enum Rmob {
     },
 }
 
+/// Executes the `rmob` application.
 pub fn run() -> BoxResult<()> {
     let rmob = Rmob::from_args();
 

src/prepare_commit_msg.rs

@@ -1,11 +1,14 @@
-//! prepare-commit-msg subcommand
+//! Subcommand for injecting `Co-authored-by` lines into Git commit messages.
 
 use std::fs;
 use std::path::Path;
 
 use crate::active_copirate::ActiveCoPirates;
 use crate::BoxResult;
 
+/// Injects `Co-authored-by` lines into the given Git commit message file.
+///
+/// This subcommand should only ever be invoked by the Git hook generated by `rmob embark`.
 pub fn inject_into_commit_message_file(
     commit_message_file: &Path,
     repo_dir: &Path,

src/sail.rs

@@ -1,4 +1,4 @@
-//! start sub-command
+//! Subcommand to begin mobbing on the active Git repository.
 
 use std::path::Path;
 
@@ -8,6 +8,7 @@ use crate::BoxResult;
 
 const COPIRATES_PATH: &str = ".git-copirates";
 
+/// Begin mobbing with the given co-authors on the Git repository located at `repo_dir`.
 pub fn sail(copirates: &[String], repo_dir: &Path) -> BoxResult<()> {
     let ship = dirs::home_dir().ok_or("Could not find yer ship oy!")?;
     let existing_copirates = CoPirates::open(&ship.join(COPIRATES_PATH))?;

src/solo.rs

@@ -1,4 +1,4 @@
-//! start sub-command
+//! Subcommand to disable mobbing for the active Git repository.
 
 use std::path::Path;