From 5cd5e4764c13dfbabd19dd5f3705705f55b23a89 Mon Sep 17 00:00:00 2001
From: Michael Bryan <michaelfbryan@gmail.com>
Date: Sun, 16 Sep 2018 23:44:52 +0800
Subject: [PATCH] Fleshed out the api docs

---
 examples/nop-preprocessor.rs | 24 ++++++++++++++++++------
 src/preprocess/cmd.rs        | 17 ++++++++++++++++-
 2 files changed, 34 insertions(+), 7 deletions(-)

diff --git a/examples/nop-preprocessor.rs b/examples/nop-preprocessor.rs
index 7c04417a..4cd8693d 100644
--- a/examples/nop-preprocessor.rs
+++ b/examples/nop-preprocessor.rs
@@ -5,6 +5,7 @@ extern crate clap;
 
 use clap::{App, Arg, ArgMatches, SubCommand};
 use mdbook::preprocess::CmdPreprocessor;
+use mdbook::book::Book;
 use std::process;
 use std::io;
 
@@ -14,18 +15,21 @@ fn main() {
     if let Some(sub_args) = matches.subcommand_matches("supports") {
         handle_supports(sub_args);
     } else {
-        handle_preprocessing(&matches);
+        handle_preprocessing();
     }
 }
 
-fn handle_preprocessing(args: &ArgMatches) {
+fn handle_preprocessing() {
     let (ctx, book) = CmdPreprocessor::parse_input(io::stdin())
         .expect("Couldn't parse the input");
 
-    eprintln!("{:?}", ctx.config);
+    // You can inspect the calling mdbook's version to check for compatibility
+    if ctx.mdbook_version != mdbook::MDBOOK_VERSION  {
+        panic!("The version check failed!");
+    }
 
-    // You can tell the preprocessor to blow up by setting a particular
-    // config value
+    // In testing we want to tell the preprocessor to blow up by setting a
+    // particular config value
     if let Some(table) = ctx.config.get_preprocessor("nop-preprocessor") {
         let should_blow_up = table.get("blow-up").is_some();
 
@@ -34,13 +38,21 @@ fn handle_preprocessing(args: &ArgMatches) {
         }
     }
 
-    serde_json::to_writer(io::stdout(), &book).unwrap();
+    let processed_book = do_processing(book);
+
+    serde_json::to_writer(io::stdout(), &processed_book).unwrap();
+}
+
+fn do_processing(book: Book) -> Book {
+    // We *are* a nop preprocessor after all...
+    book
 }
 
 fn handle_supports(sub_args: &ArgMatches) {
     let renderer = sub_args.value_of("renderer").expect("Required argument");
     let supported = renderer_is_supported(&renderer);
 
+    // Signal whether the renderer is supported by exiting with 1 or 0.
     if supported {
         process::exit(0);
     } else {
diff --git a/src/preprocess/cmd.rs b/src/preprocess/cmd.rs
index 81f8286e..f16b57da 100644
--- a/src/preprocess/cmd.rs
+++ b/src/preprocess/cmd.rs
@@ -8,12 +8,27 @@ use std::process::{Child, Command, Stdio};
 
 /// A custom preprocessor which will shell out to a 3rd-party program.
 ///
-/// # Preprocessing
+/// # Preprocessing Protocol
 ///
 /// When the `supports_renderer()` method is executed, `CmdPreprocessor` will
 /// execute the shell command `$cmd supports $renderer`. If the renderer is
 /// supported, custom preprocessors should exit with a exit code of `0`,
 /// any other exit code be considered as unsupported.
+///
+/// The `run()` method is implemented by passing a `(PreprocessorContext, Book)`
+/// tuple to the spawned command (`$cmd`) as JSON via `stdin`. Preprocessors
+/// should then "return" a processed book by printing it to `stdout` as JSON.
+/// For convenience, the `CmdPreprocessor::parse_input()` function can be used
+/// to parse the input provided by `mdbook`.
+///
+/// Exiting with a non-zero exit code while preprocessing is considered an
+/// error. `stderr` is passed directly through to the user, so it can be used
+/// for logging or emitting warnings if desired.
+///
+/// # Examples
+///
+/// An example preprocessor is available in this project's `examples/`
+/// directory.
 #[derive(Debug, Clone, PartialEq)]
 pub struct CmdPreprocessor {
     name: String,