docstr

This crate provides a macro docstr! for ergonomically creating multi-line string literals.

docstr = "0.4"

Note: docstr does not have any dependencies such as syn or quote, so compile-speeds are very fast.

Usage

docstr! takes documentation comments as arguments and converts them into a string

use docstr::docstr;

let hello_world_in_c: &'static str = docstr!(
    /// #include <stdio.h>
    ///
    /// int main(int argc, char **argv) {
    ///     printf("hello world\n");
    ///     return 0;
    /// }
);

assert_eq!(hello_world_in_c, r#"#include <stdio.h>

int main(int argc, char **argv) {
    printf("hello world\n");
    return 0;
}"#)

Composition

docstr! can pass the generated string to any macro. This example shows the string being forwarded to the format! macro:

let name = "Bob";
let age = 21;

let greeting: String = docstr!(format!
    /// Hello, my name is {name}.
    /// I am {} years old!
    age
);

assert_eq!(greeting, "\
Hello, my name is Bob.
I am 21 years old!");

This is great because there’s just a single macro, docstr!, that can do anything. No need for docstr_format!, docstr_println!, docstr_write!, etc.

How composition works

If the first argument to docstr! is a path to a macro, that macro will be called. This invocation:

let greeting: String = docstr!(format!
    /// Hello, my name is {name}.
    /// I am {} years old!
    age
);

Is equivalent to this:

let greeting: String = format!("\
Hello, my name is {name}.
I am {} years old!"
    age,
);

You can inject arguments before the format string:

docstr!(write! w
   /// Hello, world!
);

Expands to:

write!(w, "Hello, world!");

Global Import

This will make docstr! globally accessible in your entire crate, without needing to import it:

#[macro_use(docstr)]
extern crate docstr;