docs: improve doc comments

Sponsored-by: author

1 files changed, 91 insertions, 12 deletions

diff --git a/src/lib.rs b/src/lib.rs
index 0f7b2a1..d1b7bce 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -10,13 +10,42 @@
 //! - [roadmap](https://gitlab.com/larswirzenius/roadmap)
 //! - [raw SVG](https://en.wikipedia.org/wiki/Scalable_Vector_Graphics)
 //!
+//! Example:
+//!
+//! ~~~~~~markdown
+//! This is a sample Markdown file.
+//!
+//! ```dot
+//! digraph "broken" {
+//!    foo -> bar;
+//! }
+//! ```
+//! ~~~~~~
+//!
 //! The Pandoc AST has represents input as `Block` and other types of
 //! nodes. This crate turns `Block::CodeBlock` nodes that carry a
 //! class attribute that specifies one of the supported diagram markup
-//! languages into blocks with embedded SVG graphics.
+//! languages (`dot`, `plantuml`, `pikchr`, `roadmap`, `svg`) into
+//! blocks with embedded SVG graphics.
+//!
+//! Note that this library does not do any parsing of an input
+//! document. Use the [`pandoc_ast`](https://crates.io/crates/pandoc_ast)
+//! or [`pandoc`](https://crates.io/crates/pandoc) crates for that.
+//!
+//! # Example
 //!
-//! Note that this library does not do any parsing. The
-//! `pandoc_ast::filter` function does that.
+//! ```
+//! # use pandoc_filter_diagram::DiagramFilter;
+//! # let mut json = r#"{"blocks":[{"t":"CodeBlock","c":[["",["dot"],[]],"digraph \"broken\" {\n   foo -> bar;\n}"]}],"pandoc-api-version":[1,20],"meta":{}}"#;
+//! let mut df = DiagramFilter::new();
+//! let json = pandoc_ast::filter(json.to_string(), |doc| df.filter(doc));
+//! if !df.errors().is_empty() {
+//!     for e in df.errors().iter() {
+//!         eprintln!("ERROR: {}", e);
+//!     }
+//!     std::process::exit(1);
+//! }
+//! ```
 
 use pandoc_ast::{Block, Inline, MutVisitor, Pandoc};
 use std::env;
@@ -25,7 +54,20 @@ use std::io::{Read, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Command, Stdio};
 
-/// Represent the diagram filter.
+/// Convert inline diagram markup as images for Pandoc.
+///
+/// This acts a filter on the Pandoc Abstract Syntax Tree (AST), to
+/// modify it so that any inline markup for diagrams are rendered as
+/// SVG images. The library is meant to be used with the
+/// `pandoc_ast::filter` function.
+///
+/// Filtering may fail. Because of the API constrain imposed by
+/// `pandoc_ast::filter`, this library doesn't return a `Result`.
+/// Instead, it collects any errors and lets the caller query for them
+/// after the filtering is done (see the
+/// [`errors`](DiagramFilter::errors) method). All errors are always
+/// rendered as text in the document as well, but that requires a
+/// human to read the document to spot any errors.
 #[derive(Debug)]
 pub struct DiagramFilter {
     dot: PathBuf,
@@ -40,7 +82,9 @@ pub struct DiagramFilter {
 pub enum DiagramError {
     /// When rendering a pikchr, something went wrong.
     #[error("failure rendering pikchr diagram: {0}")]
-    PikchrRenderError(String),
+    PikchrRenderError(
+        /// The error message from pikchr.
+        String),
 
     /// When rendering a roadmap, something went wrong.
     #[error("failure rendering roadmap diagram: {0}")]
@@ -51,7 +95,15 @@ pub enum DiagramError {
     /// This Pandoc filter uses some helper programs to do some of its
     /// work. It failed to invoke such a helper program.
     #[error("failed to invoke helper program {0} (as {1}): {2}")]
-    InvokeFailed(String, PathBuf, String),
+    InvokeFailed(
+        /// Name of the program.
+        String,
+
+        /// Path with which the program was invoked.
+        PathBuf,
+
+        /// Standard error output of program.
+        String),
 
     /// A helper program failed
     ///
@@ -63,7 +115,18 @@ pub enum DiagramError {
     /// This probably implies there's something wrong in the filter.
     /// Please report this error.
     #[error("helper program failed: {0} (as {1}), exit status {2}:\n{3}")]
-    HelperFailed(String, PathBuf, String, String),
+    HelperFailed(
+        /// Name of the program.
+        String,
+
+        /// Path with which the program was invoked.
+        PathBuf,
+
+        /// How did the program end? Status code or signal?
+        String,
+
+        /// Standard error output of program.
+        String),
 
     /// I/O error
     ///
@@ -76,6 +139,7 @@ pub enum DiagramError {
 type Svg = Vec<u8>;
 
 impl Default for DiagramFilter {
+    /// Create a filter with default settings.
     fn default() -> Self {
         Self {
             dot: PathBuf::from("dot"),
@@ -88,14 +152,28 @@ impl Default for DiagramFilter {
 }
 
 impl DiagramFilter {
+    /// Create a new filter.
     pub fn new() -> Self {
         Self::default()
     }
 
+    /// Process a parsed document to convert inline diagram markup
+    /// into SVG. This method is suitable to be passed to
+    /// `pandoc_ast::filter` as the filter function argument.
+    pub fn filter(&mut self, mut doc: Pandoc) -> Pandoc {
+        self.walk_pandoc(&mut doc);
+        doc
+    }
+
+    /// Return any errors that occurred during the filtering process.
+    /// The caller can decide how to report them to the user in a
+    /// suitable way.
     pub fn errors(&self) -> &[DiagramError] {
         &self.errors
     }
 
+    /// Set the name by which to invoke Graphviz `dot` program. The
+    /// default is "`dot`".
     pub fn dot_path<P>(&mut self, path: P) -> &mut Self
     where
         P: AsRef<Path>,
@@ -104,6 +182,8 @@ impl DiagramFilter {
         self
     }
 
+    /// Set the name by which to invoke the Java runtime, for
+    /// PlantUML. The default is "`java`".
     pub fn java_path<P>(&mut self, path: P) -> &mut Self
     where
         P: AsRef<Path>,
@@ -112,6 +192,8 @@ impl DiagramFilter {
         self
     }
 
+    /// Set the location of the PlantUML jar (Java bytecode archive).
+    /// The default is "`/usr/share/plantuml/plantuml.jar`".
     pub fn plantuml_jar<P>(&mut self, path: P) -> &mut Self
     where
         P: AsRef<Path>,
@@ -120,16 +202,13 @@ impl DiagramFilter {
         self
     }
 
+    /// Set the maximum width, in characters, of the roadmap text
+    /// nodes. The default is 50.
     pub fn roadmap_width(&mut self, w: usize) -> &mut Self {
         self.roadmap_width = w;
         self
     }
 
-    pub fn filter(&mut self, mut doc: Pandoc) -> Pandoc {
-        self.walk_pandoc(&mut doc);
-        doc
-    }
-
     fn error_block(&self, error: &DiagramError) -> Block {
         let msg = Inline::Str(format!("ERROR: {}", error.to_string()));
         let msg = vec![Inline::Strong(vec![msg])];