Fleshed out the api docs

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 {

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,