rustdoc fails on `ignore`'d code

[steveklabnik]

This doc example:

/// ```ignore
/// let heart = '❤️';
/// ```

compiles and passes with rustdoc --test, but not just generating documentation.

[fhahn]

I took a look at this and it seems like your char literal contains another (apparently invisible) code point, which means it is no valid Rust code.

The problem seems to be that rustdoc tries to highlight the code regardless of the ignore annotation, as it only ignores the snippet when running tests. And AFAIK rustdoc uses libsyntax's parser to do that, which will complain about the additional codepoint.

While the error is confusing (because there is no visible additional code point), I think the behavior of rustdoc is OK. Otherwise we would also have to exclude ingored code from the documentation, which means ignored code in docs would be rather pointless.

Finally this code should work with rustdoc, because both hearts are single codepoints

/// ```ignore
/// let foo = '♥'; // U+2665
/// let foo = '❤'; // U+2764
/// ```
pub fn this_is_a_function() {}

[steveklabnik]

I took a look at this and it seems like your char literal contains another (apparently invisible) code point, which means it is no valid Rust code.

Yes. That's why it's in ignore.

Otherwise we would also have to exclude ingored code from the documentation, which means ignored code in docs would be rather pointless.

Or maybe not syntax highlight code that's ignored?

[fhahn]

I think it would still make sense to have an annotation which excludes the code from the tests but highlights it in the docs, e.g. for nice looking example code, which does not have to include every little detail to make it compile.

If one would like to include code that should not be highlighted and not be used when testing, wouldn't it be possible to just add it as normal text, not in a code block?

[steveklabnik]

Triage: looks like #33510 didn't happen

[JeanMertz]

I ran into this today. I use ```ignore to add compiler error descriptions to my crate docs, which is documented in the book, but as soon as I tried to run $ rust doc, it failed because it tried compile the non-Rust characters in that code block as Rust code.

I'm surprised this issue hasn't had any responses since 2016, so either this is already solved and I'm hitting some other issue, or people don't really put non-Rust code blocks in their documentation.

Here's part of the documentation that currently fails.