rustdoc incorrectly handles ##

[lcnr]

I tried this code:

/// ```rust
/// ##![no_std]
/// ```
pub struct A;

with cargo doc

I expected to see this happen: Either an error or #![no_std] gets hidden

What actually happend: The first # gets ignored.

[GuillaumeGomez]

A fix to this issue is present in this PR apparently (or maybe I understood it incorrectly?).

[lcnr]

Not sure, does #74094 change the way # is handled in code snippets?

[GuillaumeGomez]

I think it does: https://github.com/rust-lang/rust/pull/74094/files#diff-545d93b02fb448fc31d33a6b1e0e0c48R136-R153 At least it's changing the code handling it...

[lcnr]

So it seems like it was a conscious decision to print ##abc as #abc :/

Can we still change this/what was the reason for this decision?
Otherwise this can just be closed as it seems like this behavior is intended.

[GuillaumeGomez]

Well, I have to admit that it seems weird and I wonder if it isn't just a side-effect more than a desired behavior. What do you think @rust-lang/rustdoc ?

[Mark-Simulacrum]

See #41785 where the behavior for ## was introduced. If you want to hide #![no_std] you want to use # #![no_std], ##![no_std] is changed to #![no_std] I believe.

[GuillaumeGomez]

Should we maybe add a lint for it?

[Mark-Simulacrum]

I am confused -- the behavior may not be entirely intuitive, but linting would seem odd, as either case is entirely reasonable.

[GuillaumeGomez]

I completely agree but the confusion seems logical. So having a lint you can easily discard might be a good solution to help users when they have such a case, no?

[Mark-Simulacrum]

I disagree that we should have lints that are (not infrequently) allow'd in rustdoc/rustc; that seems more like clippy territory. It's also true that I don't think we have a good story for allowing lints that rustdoc emits today?

[GuillaumeGomez]

It's being improved currently, but as far as I can see, the rustdoc lints are fine.

[ollie27]

A lint would be overly complicated for this. The behavior is documented at https://doc.rust-lang.org/nightly/rustdoc/documentation-tests.html#hiding-portions-of-the-example but maybe it can be improved to make it clear that you need a space after the hash for a line to be hidden.

[GuillaumeGomez]

I didn't even think about the implementation when talking about the lint. It's just that I don't really know how to avoid such a case and help users in case it's a typo. Documentation exists but it's pretty rare for users to actually go read it when they have troubles unfortunately...

[Mark-Simulacrum]

I think we don't have sufficient cause for this to merit adding a lint - the input on this case isn't valid Rust, nor could it be; as such I would expect it to be quite rare to encounter in practice (and even on accident). It's also harmless if you do want to show the attribute (and if you don't, IMO adding a space is not entirely unintuitive, though I could be wrong about that, seeing as this thread suggests otherwise to some extent).

[GuillaumeGomez]

Well, this current case is a good example. 😉 But honestly, I feel like any additional check would be overkill here... So I really don't know what to do in here except nothing.