svgbobdoc

This crate provides a procedural macro that renders ASCII diagrams in doc comments as SVG images using [svgbob].

Usage

Add the following line to Cargo.toml.

toml [dependencies] svgbobdoc = "0.2"

Add the attribute #[svgbobdoc::transform] to the items to documentate. Use svgbob code blocks to write ASCII diagrams.

#[svgbobdoc::transform]
/// Some structure.
///
/// ```svgbob
///  .--------------------.
///  | Diagrams here      |
///  `--------------------'
/// ```
pub struct TestStruct {}

See the example directory for a complete example.

Tips

• Using this macro increases the compilation time. If you don't mind activating unstable features, the doc_cfg feature ([#43781]) can be used to conditionally enable the macro by the syntax #[cfg_attr(doc, svgbobdoc::transform)].

Other forms of macros

The macro is currently implemented as an attribute macro, which has restrictions, e.g., they cannot be attached to fields and non-inline modules. Other forms of macros were considered, but they were unusable for this purpose for the following reasons:

• Function-like macros producing a string literal (#[doc = svgbobdoc::to_svg!("...")]): Macros in this position aren't expanded, causing a parsing error.

• Function-like macros producing a part of an attribute (#[svgbobdoc::doc!("...")]): Macros in this position aren't expanded, causing a parsing error.

• Function-like macros expanding to an attribute (svgbobdoc::doc!("...")): Procedural macros cannot expand to an attribute.

Therefore, despite its downsides, an attribute macro is the only working solution known at the moment.

License: MIT/Apache-2.0