[rustdoc] Add no-hidden-lines codeblock attribute by GuillaumeGomez · Pull Request #118711 · rust-lang/rust (original) (raw)

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:

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

Concerns

r? @notriddle