[−][src]Crate 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
.
[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.
Attribute Macros
transform | Render ASCII-diagram code blocks in doc comments as SVG images. |