readme: update

Rewrite the README and the source comments in a plainer register.

The README had picked up the usual generated-prose tics: seventeen em
dashes, inline bold headers over every work item, signposting lines like
'the two scripts are called out because it matters', and a two-word
'Twenty of them.' dropped in for emphasis. Replaced with commas, real
section headings, and sentences that carry their own subject.

Also fixes the two rustdoc warnings cargo doc was emitting: <NAME> and
<N> in the subcommand doc comments were being parsed as unclosed HTML
tags. cargo doc is clean now.

src/cli.rs

@@ -1,5 +1,5 @@
-//! The whole command surface, in one file, so the shape of the CLI reads at a
-//! glance. Nothing here does any work — every variant is dispatched in `main`.
+//! The whole command surface in one file, so the CLI is readable end to end.
+//! Nothing here does any work: every variant is dispatched in `main`.
 
 use std::path::PathBuf;
 
@@ -71,11 +71,11 @@ pub enum PatchCommand {
     Format(FormatArgs),
     /// Commit the work in progress with a kernel-style message
     Commit(CommitArgs),
-    /// Write the diff against the base branch out to <NAME>.patch
+    /// Write the diff against the base branch out to a .patch file
     Create(CreateArgs),
     /// Send a patch, with To/CC taken from get_maintainer.pl
     Submit(SubmitArgs),
-    /// Re-roll a patch as v<N>, renaming the file to match
+    /// Re-roll a patch as vN, renaming the file to match
     Update(UpdateArgs),
 }
 

src/config.rs

@@ -1,7 +1,7 @@
 //! Where the kernel tree and the patches live.
 //!
-//! Everything else asks this module for paths, so the day a config file or
-//! `spectral init` arrives, it is the only thing that changes.
+//! Everything else asks this module for paths, so adding a config file or a
+//! `spectral init` only touches this file.
 
 #![allow(dead_code)] // accessors are read once the patch verbs stop being stubs
 
@@ -29,9 +29,9 @@ impl Config {
     /// Resolve the tree from `$SPECTRAL_KERNEL`, falling back to
     /// `~/.spectral/linux`.
     ///
-    /// The tree is not checked for existence here — commands that need it call
-    /// [`Config::require_kernel_tree`], so `kernel quest` still works before
-    /// anything is cloned.
+    /// The tree is not checked for existence here. Commands that need it call
+    /// [`Config::require_kernel_tree`], which leaves `kernel quest` working
+    /// before anything is cloned.
     ///
     /// TODO: also read `~/.config/spectral/config.toml` once `spectral init`
     /// exists. The environment variable should keep winning over the file.
@@ -56,7 +56,7 @@ impl Config {
         &self.patch_dir
     }
 
-    /// The kernel tree, having confirmed it is one.
+    /// Resolve the tree and check that it really is a kernel source tree.
     pub fn require_kernel_tree(&self) -> Result<&Path> {
         if self.kernel_tree.join("scripts/checkpatch.pl").is_file() {
             Ok(&self.kernel_tree)

src/error.rs

@@ -1,7 +1,7 @@
 //! One error type for the whole CLI.
 //!
-//! Anything that can go wrong ends up as an [`Error`], gets a `?` at the call
-//! site, and is printed once in `main` — no `unwrap` in the command paths.
+//! Everything that can go wrong ends up as an [`Error`], gets a `?` at the
+//! call site, and is printed once by `main`.
 
 use std::path::PathBuf;
 

src/git.rs

@@ -1,6 +1,6 @@
 //! Thin plumbing over the `git` binary.
 //!
-//! Nothing in here knows what a kernel is: it starts processes, hands back
+//! Nothing in here knows what a kernel is. It starts processes, returns
 //! stdout, and turns a non-zero exit into an [`Error`].
 
 #![allow(dead_code)] // reachable as soon as the patch verbs stop being stubs
@@ -28,8 +28,8 @@ impl Git {
 
     /// Run git in the repository and return its trimmed stdout.
     ///
-    /// This is the only place a git process is started; the semantic
-    /// operations below are written in terms of it.
+    /// This is the only place a git process is started. Every other method
+    /// here goes through it.
     pub fn run(&self, args: &[&str]) -> Result<String> {
         let output = Command::new("git")
             .arg("-C")

src/kernel/qemu.rs

@@ -1,4 +1,4 @@
-//! `spectral kernel test` — build the tree, then boot it under qemu.
+//! `spectral kernel test`: build the tree, then boot it under qemu.
 
 #![allow(dead_code)] // nothing is reachable until `run` stops being a stub
 

src/kernel/quest.rs

@@ -1,8 +1,7 @@
-//! `spectral kernel quest` — go and find something worth fixing.
+//! `spectral kernel quest`: go and find something worth fixing.
 //!
-//! The source is behind [`QuestSource`] so swapping bugzilla for syzbot, a
-//! lore.kernel.org thread, or a local TODO file is one new impl and no change
-//! to the command.
+//! The source sits behind [`QuestSource`], so adding a local TODO file or a
+//! syzbot scraper later means one new impl and no change to the command.
 
 #![allow(dead_code)] // nothing is reachable until `run` stops being a stub
 

src/main.rs

@@ -1,7 +1,8 @@
-//! spectral — a monolithic kernel work wrapper to make it easy.
+//! spectral: a monolithic kernel work wrapper to make it easy.
 //!
-//! `main` does three things: parse, dispatch, render. Anything with a kernel
-//! or git in it lives behind one of the modules below.
+//! `main` parses the command line, dispatches to a module, and prints what
+//! comes back. Anything that touches a kernel or a git repository lives in one
+//! of the modules below.
 
 mod cli;
 mod config;
@@ -31,8 +32,8 @@ async fn main() -> ExitCode {
     }
 }
 
-/// The command modules do the work and hand back what they produced; printing
-/// it is `main`'s job.
+/// Command modules do the work and return what they produced. Printing it is
+/// `main`'s job.
 async fn run(cli: Cli) -> Result<()> {
     let config = Config::load()?;
 

src/patch/checkpatch.rs

@@ -1,4 +1,4 @@
-//! `scripts/checkpatch.pl`, run the two ways spectral needs it.
+//! `scripts/checkpatch.pl`, from the kernel tree you are working in.
 
 #![allow(dead_code)] // reachable as soon as the patch verbs stop being stubs
 
@@ -36,9 +36,9 @@ impl Report {
 
 /// Run checkpatch.pl over `target`.
 ///
-/// `fix` adds `--fix`, which rewrites the patch file in place — only
-/// `Target::File` supports it, and the caller is responsible for having the
-/// change committed first so a bad fix is one `git checkout` away.
+/// `fix` adds `--fix`, which rewrites the patch file in place. Only
+/// `Target::File` supports it, and the caller has to have the change
+/// committed first so a bad fix can be reverted.
 pub fn run(kernel_tree: &Path, target: &Target, strict: bool, fix: bool) -> Result<Report> {
     todo!(
         "scripts/checkpatch.pl --no-tree in {} on {target:?} (strict={strict}, fix={fix})",

src/patch/maintainers.rs

@@ -19,8 +19,8 @@ pub struct Recipients {
 
 /// Look up recipients for a patch.
 ///
-/// Runs `get_maintainer.pl --roles=... --git` over the patch's diff, which is
-/// what gives us the files it touches as a side effect.
+/// Runs `get_maintainer.pl --roles=... --git` over the patch's diff. That also
+/// gives us the files the patch touches.
 pub fn lookup(kernel_tree: &Path, patch: &Path) -> Result<Recipients> {
     todo!("get_maintainer.pl --git on {patch:?} inside {kernel_tree:?}")
 }

src/patch/mod.rs

@@ -1,7 +1,6 @@
-//! `spectral patch …` — carry a change from working tree to mailing list.
+//! `spectral patch`: carry a change from working tree to mailing list.
 //!
-//! The verbs are all stubs, but the order they are meant to be run in is the
-//! point of the module:
+//! The verbs are all stubs. The order they are meant to be run in is:
 //!
 //! ```text
 //! check ─▶ format ─▶ commit ─▶ create ─▶ submit
@@ -9,8 +8,8 @@
 //!                                  └─ update┘   (v2, v3, …)
 //! ```
 //!
-//! Each verb resolves the tree through [`Config::require_kernel_tree`] and
-//! builds a [`crate::git::Git`] over it; that is how they reach the plumbing.
+//! Each verb gets the tree from [`Config::require_kernel_tree`] and builds a
+//! [`crate::git::Git`] over it, which is how it reaches the plumbing.
 
 pub mod checkpatch;
 pub mod maintainers;
@@ -51,9 +50,8 @@ pub fn create(config: &Config, args: CreateArgs) -> Result<PathBuf> {
 
 /// Send a patch to whoever `get_maintainer.pl` names.
 ///
-/// `--dry-run` stops one step short: print the recipients and the exact
-/// `git send-email` invocation instead of sending it, which is the honest way
-/// to review a first submission to a list.
+/// With `--dry-run` it prints the recipients and the exact `git send-email`
+/// invocation instead of sending anything.
 pub fn submit(config: &Config, args: SubmitArgs) -> Result<()> {
     let _ = (config, args);
     todo!("look up recipients, then git send-email")