[rustdoc] Add no-hidden-lines codeblock attribute

[GuillaumeGomez]

Fixes #118027.

Motivation

When documentation macro and proc-macro, there is currently an extra layer of complexity to take into account when it uses # characters. Allowing to disable this rustdoc behaviour with a codeblock attribute would make this task much simpler for (proc) macro documentation writers.

Example from #118027:

define_component!(
    #[derive(Debug)]
    ##[min(0.0))]
    ##[max(100.0))]
    ##[default(50.0)]
    pub Fuel(pub f32);
);

in documentation codeblocks becomes:

define_component!(
    #[derive(Debug)]
    #[min(0.0))]
    #[max(100.0))]
    #[default(50.0)]
    pub Fuel(pub f32);
);

Generating invalid documentation for end users.

What is this feature about?

It is about adding a new no-hidden-lines codeblock attribute which would remove this # character cleanup pass in order to make it easier for (proc) macro API to have code examples.

The no-hidden-lines attribute works just like should_panic or ignore attributes: if there are no other tags, it'll consider the code block as a rust one and hence will test it.

Example of usage:

```no-hidden-lines
define_component!(
    #[derive(Debug)]
    ##[min(0.0))]
    ##[max(100.0))]
    ##[default(50.0)]
    pub Fuel(pub f32);
);
```

Concerns

• Is no-hidden-lines the right name for this codeblock attribute?
• Is this codeblock attribute really necessary?

r? @notriddle

[Urgau]

Wouldn't it be simpler to have disambiguator so that you could still hide (for example your imports) ?

Using your example it wouldn't be possible to show #a, ##b and ###c but hide the import.

//! ```rust,raw
//! # use crate::test;  // this should be hidden
//!
//! test!(
//!     #a,             // but not thoses
//!     ##b,
//!     ###c
//! );
//! ```

[GuillaumeGomez]

Macros are a nightmare on their own. You could very well have:

//! ```rust,raw
//! # use crate::test;  // this should be hidden
//!
//! test!(
//!     # use something::other;
//! );
//! ```

[notriddle]

Is raw the right name for this codeblock attribute?

Not really. It should be more descriptive, like no_hidden_lines.

Is this codeblock attribute really necessary?

I'm curious how this will interact with custom. I know if it's used, custom should solve this same problem (at the cost of disabling syntax highlighting entirely).

Would turning syntax highlighting off entirely be an acceptable compromise? On the one hand, syntax highlighting doesn't seem very helpful with a huge macro DSL anyway, since rustdoc won't know anything about the syntax of the macro, but, on the other hand, it might work fine if the macro embeds lots of normal Rust code (or is intentionally designed to use Rust keywords for its own keywords instead of making them up).

[GuillaumeGomez]

Using custom would also mean no doctest, which I think would be a bigger problem than not having syntax highlighting.

[notriddle]

That's what it looks like to me, too, though I can't find any test cases for that (should probably add one).

I know #78917 wanted a way to have doctested code without syntax highlighting. Is there any way to do that right now?

[GuillaumeGomez]

No, doctests are only rust codeblocks. And rust codeblocks have syntax highlighting.

[notriddle]

That's weird... #78917 wanted to turn syntax highlighting off while leaving doctesting on (though they still wanted hidden lines).

So, reading through that issue again, I guess no_hidden_lines is the best name for this option, since it's orthogonal to the actual question of syntax highlighting.

[GuillaumeGomez]

Indeed. I'll also use the opportunity to rebase to fix the CI failure.

[rustbot]

Could not assign reviewer from: notriddle.
User(s) notriddle are either the PR author, already assigned, or on vacation, and there are no other candidates.
Use r? to specify someone else to assign.

[GuillaumeGomez]

Renamed the codeblock attribute to no-hidden-lines.

[notriddle]

I see that this isn't gated behind a feature flag. Is that intentional?

(I'm fine either way, but if it's going to be insta-stable then it's going to need to go through an FCP.)

[GuillaumeGomez]

It's what I want indeed but in any case I'd like us to go through FCP so every one can check it.

[notriddle]

@rfcbot fcp merge

[rfcbot]

Team member @notriddle has proposed to merge this. The next step is review by the rest of the tagged team members:

• @GuillaumeGomez
• @Manishearth
• @Nemo157
• @aDotInTheVoid
• @camelid
• @jsha
• @notriddle

Concerns:

• is-this-a-bug ([rustdoc] Add no-hidden-lines codeblock attribute #118711 (comment))
• why is this insta stable? ([rustdoc] Add no-hidden-lines codeblock attribute #118711 (comment))

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[aDotInTheVoid]

@rfcbot concern why is this insta stable?

Otherwise this looks good

[GuillaumeGomez]

It seemed small enough to me (it's a new codeblock attribute for a very specific use-case). If it's an issue I can put it behind a feature. Just seems not worth it.

[Nemo157]

From the docs, line hiding only occurs on # , so the only time we need to do the replacement is ## => # not ##[ => #[; that seems like it might be backwards compatible to fix (EDIT: or maybe if there are people using ###[ already to work around the issue, it could be an edition fix).

[Manishearth]

@rfcbot concern is-this-a-bug

I'm not convinced the behavior where indented pound symbols are hidden is not a bug. I didn't even know we did that, I always thought it only applied to lines that start with a pound symbol.

If we were designing the feature today I would have been pretty strongly against having it apply to all pound signs regardless of indentation.

It would be somewhat breaking but it's worth figuring out how many crates out there actually use this when indented.

[GuillaumeGomez]

From the docs, line hiding only occurs on # , so the only time we need to do the replacement is ## => # not ##[ => #[; that seems like it might be backwards compatible to fix (EDIT: or maybe if there are people using ###[ already to work around the issue, it could be an edition fix).

That's why I went with raw as tag originally. I can revert this part of the change if wanted. Might be worth checking if we can remove it.

@rfcbot concern is-this-a-bug

I'm not convinced the behavior where indented pound symbols are hidden is not a bug. I didn't even know we did that, I always thought it only applied to lines that start with a pound symbol.

If we were designing the feature today I would have been pretty strongly against having it apply to all pound signs regardless of indentation.

It would be somewhat breaking but it's worth figuring out how many crates out there actually use this when indented.

I can send a PR tomorrow removing this behaviour so we can make a crater run.

[bors]

☔ The latest upstream changes (presumably #118900) made this pull request unmergeable. Please resolve the merge conflicts.