From d4a3267c5486ffecada592d7e0889d6cfa5893a3 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 11 Dec 2021 10:06:39 +0200 Subject: docs: improve doc comments Sponsored-by: author --- src/lib.rs | 103 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file 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; 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

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -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

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -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

(&mut self, path: P) -> &mut Self where P: AsRef, @@ -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])]; -- cgit v1.2.1