Are there any advantages to using docstr instead of r#" syntax?

[Tahaa-Dev]

So I have a small question, are there any advantages to using docstr instead of r#" syntax? This snippet:

const S: &'static str = docstr!(
    /// &'static str content
    /// Other content
);

Is the exact same as this one:

const S: &'static str = r#"&'static str content
Other content
"#;

and passing macros is also unaffected:

let file_name = "file.rs";
docstr!(format!
    /// [INFO] current status:
    /// Reading file: {}
    file_name
);

Is the same as:

let file_name = "file.rs";
format!(r#"[INFO] current status:
    Reading file: {}"#, file_name);

So what's the difference?

[nik-rev]

Embedding formatted text in Rust's string literals forces us to make a choice:

• Sacrifice readability of the output
• Sacrifice readability of the source code

Sacrifice readability of the output

In order to print the following:

create table student(
    id int primary key,
    name text
)

The initial attempt might look as follows:

fn main() {
    println!("
        create table student(
            id int primary key,
            name text
        )
    ");
}

Which outputs (using ^ to mark the beginning of a line, and · to mark a leading space):

^
^········create table student(
^············id int primary key,
^············name text
^········)
^····
^

The output is formatted in an unconventional way, containing excessive leading indentation.

The alternative allows for a sane output, but at the cost of making the code less readable:

Sacrifice readability of the source code

In order for the output to be more sensible, we must sacrifice readability of the source code:

fn main() {
    println!(
        "\
create table student(
    id int primary key,
    name text
)");
}

The above example would output the expected:

create table student(
    id int primary key,
    name text
)

But the improvement in output comes at a cost:

1. We now have to escape the first newline:

   fn main() {
       println!(
   +       "\
   create table student(
       id int primary key,
       name text
   )");
   }

   This is not possible to do in raw strings, so the output ends up looking even worse for them, with indentation of the outer SQL statement being larger in the source code than the inner statement:

   fn main() {
       println!(
   +       r#"create table student(
       id int primary key,
       name text
   )"#);

2. The SQL statement does not have any indentation in reference to the surrounding code.

   This is contrary to how we would normally write code, with indentation 1 level deeper than the surrounding.

   fn main() {
       println!(
           "\
   +create table student(
   +   id int primary key,
   +   name text
   +)");
   }

   This makes it confusing to tell which scope the string belongs to. This is especially true when there are multiple scopes involved:

   fn main() {
       {
           println!(
               "\
   create table student(
      id int primary key,
      name text
   )");
       }
       println!(
           "\
   create table student(
      id int primary key,
      name text
   )");
       {
           {
               println!(
                   "\
   create table student(
      id int primary key,
      name text
   )");
            
           } 
       }
   }

   All of the strings end up on the same level, despite them being in different scopes.

3. The closing double-quote must be put at the beginning of the line, in order not to introduce trailing horizontal whitespace:

   fn main() {
       println!(
           "\
   create table student(
       id int primary key,
       name text
   +)");
   }

As you can see, we have to choose one or the other. In either case we have to give something up.

Another way to format the above would be the following:

fn main() {
    println!(concat!(
        "create table student(\n",
        "    id int primary key,\n",
        "    name text,\n",
        ")\n",
    ));
}

The above:

• Is formatted nicely by rustfmt
• Produces the correct output

However, it looks very noisy.

• Each line ends with an escaped \n.
• Requires double-quotes around each line.
• This does not allow for interpolations, such as {variable_name} as the format string is expanded by a macro.

Sometimes, we are forced into the first option - sacrificing readability of the source.

In some cases, producing excessive whitespace will change meaning of the output.

Consider whitespace-sensitive languages such as Python or Haskell, or content which is meant to be read by people like generated Markdown - here we can't make a sacrifice on readabilty of the output - so our source code must become harder to understand.

But, what if we could have the best of both worlds?

That's what docstr! gives you!

fn main() {
    docstr!(println!
        /// create table student(
        ///     id int primary key,
        ///     name text
        /// )
    );
}