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.

[JeanMertz]

Here's part of the documentation that currently fails.

FYI: changing this from using ignore tags to using text made things work as expected.

[kadiwa4]

Triage: rustdoc outputs this:

warning: could not parse code block as Rust code
 --> src/lib.rs:1:5
  |
1 |   /// ```ignore
  |  _____^
2 | | /// let heart = '❤️';
3 | | /// ```
  | |_______^
  |
help: `ignore` code blocks require valid Rust code for syntax highlighting; mark blocks that do not contain Rust code as text: ```text
 --> src/lib.rs:1:5
  |
1 | /// ```ignore
  |     ^^^
  = note: error from rustc: character literal may only contain one codepoint
  = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default

but in the generated docs, it uses correct syntax highlighting on the broken code.

I think that's pretty optimal. If I understand correctly, this issue was filed because rustdoc used to abort doc-generation on encountering something like this?

[steveklabnik]

this issue was filed because rustdoc used to abort doc-generation on encountering something like this?

I believe so, but to be honest, that diagnostic output looks great to me, and there's a path to having incorrect things be documented, so as far as I'm concerned, I don't personally feel this is an issue anymore, so happy to close it, regardless of whatever historical behavior may or may not have been happening way back then.