Rustdoc escaping problem

So I have the following macro for my token types:

macro_rules! tokens {
	($($name:ident: $chr:literal)*) => {
		pub enum TokenType {
			$(#[doc=$chr] $name,)*
		}
	}
}

and I'm using it like this:

tokens! {
	Plus: "+"
	Minus: "-"
	Bang: "!"
    GreaterThan: ">"
	Asterisk: "*"
	//...
}

and what I hoped to do is that rustdoc directly writes these literals as a documentation. However, I have a problem for Plus, Minus, Asterisk and GreaterThan, the others work fine. Here is the generated HTML for them:

</div><h3 id="variant.Plus" class="variant small-section-header"><a href="#variant.Plus" class="anchor field"></a><code>Plus</code></h3><div class="docblock"><ul><li></li></ul>

</div><h3 id="variant.Minus" class="variant small-section-header"><a href="#variant.Minus" class="anchor field"></a><code>Minus</code></h3><div class="docblock"><ul><li></li></ul>

</div><h3 id="variant.Asterisk" class="variant small-section-header"><a href="#variant.Asterisk" class="anchor field"></a><code>Asterisk</code></h3><div class="docblock"><ul><li></li></ul>

</div><h3 id="variant.GreaterThan" class="variant small-section-header"><a href="#variant.GreaterThan" class="anchor field"></a><code>GreaterThan</code></h3><div class="docblock"><blockquote></blockquote>

whereas Bang which work properly gives:

</div><h3 id="variant.Bang" class="variant small-section-header"><a href="#variant.Bang" class="anchor field"></a><code>Bang</code></h3><div class="docblock"><p>!</p>

is this a rustdoc bug or am I doing something wrong ?

Edit

After trying to replace "+" with "&plus;" (HTML code for +), the documentation is displaying it properly. How could I do what I want to do but keep these chr as human readable?

Edit 2

Is it because of this pattern matching here? > seems to be already there though. Anyway, I would be glad (I'm new) to contribute to add the characters in this question.

Edit 3

Another weird thing is that it apparently works when I'm doing:

#[doc="This is a +"]
#[doc="+This is a"]

It is a markdown problem. You can wrap them with backticks like `+` to escape via code block.

1 Like

the thing is that I'm using this string to be able to construct my enum as such (inside my macro):

impl TokenType {
	pub fn from_str(s: &str) -> Result<Self, String> {
		match s {
			$($chr => Ok(Self::$name),)*
			t => Err(format!("Invalid Token: [{}]", t)),
		}
	}
}

I cannot add the ` character without impacting my code.

What about adding it to just the generated docs?

macro_rules! tokens {
	($($name:ident: $chr:literal)*) => {
		pub enum TokenType {
			$(
                  #[doc="`"]
                  #[doc=$chr]
                  #[doc="`"]
                   $name,
              )*
		}
	}
}
1 Like

works for Bang but not these

The paste crate has some support for concatenating string arguments of doc attributes. I'm on mobile now, so excuse the formatting and the fact that it's untested, but something like

paste::paste!{
    pub enum TokenType {
        $(
            #[doc="`" $chr "`"]
            $name,
        )*
    }
}

(inside of the macro definition)

might do the job.

2 Likes

This is working fine with this crate, thanks! Still wondering if there is a "non-external dependency" way of doing this though

Wouldn't just concat work here as well?

macro_rules! tokens {
    ($($name:ident: $chr:literal)*) => {
        pub enum TokenType {
            $(
                #[doc = concat!("`", $chr, "`")]
                $name,
            )*
        }
    }
}
4 Likes

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.