`/// # #![rustfmt::skip]` behaves weird

[max-ishere]

trafficstars

I just wanted to keep specific formatting in my list. However it wasn't so easy...

skip visible in the HTML

Source code

//! ```rust
//! #![rustfmt::skip]
//! let _ = [
//!     1, 2, 3,
//!     4, 5,
//! ];
//! ```

Rendered doc

#![rustfmt::skip]
let _ = [
    1, 2, 3,
    4, 5,
];

This works, but I want to hide the formatting attribute

Hiding the skip

Before save:

//! ```rust
//! # #![rustfmt::skip]
//! let _ = [
//!     1, 2, 3,
//!     4, 5,
//! ];
//! ```

On save the list is formatted:

//! ```rust
//! # #![rustfmt::skip]
//! let _ = [1, 2, 3, 4, 5];
//! ```

Another way to hide skip with a block

Source code

//! ```rust
//! # #![rustfmt::skip] {
//! let _ = [
//!     1, 2, 3,
//!     4, 5
//! ];
//! }
//! ```

No difference on save, but its a new scope so now this variable is not avaliable to unformatted code.

Rendered HTML

let _ = [
    1, 2, 3,
    4, 5
];
}

Contains trailing }. If you hide the closing brace rustfmt will format the list.

Using nofmt::pls!{}

Source code

//! ```rust
//! let _ = nofmt::pls! {[
//!     1, 2, 3,
//!     4, 5
//! ]};
//! ```

Rendered doc

let _ = nofmt::pls! {[
    1, 2, 3,
    4, 5
]};

Hiding nofmt::pls!{}

Source code

//! ```rust
//! let _ =
//! # nofmt::pls! {
//! [
//!     1, 2, 3,
//!     4, 5
//! ];
//! # }
//! ```

No change on save.

Rendered doc

let _ =
[
    1, 2, 3,
    4, 5
];

But this just looks weird, I want to try to put the open bracket on the same line as =. I don't want the doc to look completely unformatted, just a little bit in a subtle way so that my list is more readable.

Making nofmt::pls!{} more hidden

Source code

//! ```rust
//! let _ = [
//! # nofmt::pls! {
//!     1, 2, 3,
//!     4, 5
//! # }
//! ];
//! ```

On save:

//! ```rust
//! let _ = [
//! # nofmt::pls! {
//!     1, 2, 3, 4, 5, //#### # }
//! ];
//! ```

Ouch... I think this is realted to #6025

Versions

rustfmt 1.7.0-nightly (3246e79 2024-02-19)
cargo 1.78.0-nightly (7b7af3077 2024-02-17

[ytmimi]

@max-ishere Thanks for reaching out. Currently there's no good way to skip formatting in a code block when using format_code_in_doc_comments I gave a brief explanation about what rustfmt is looking for in order to determine if it should reformat code in doc comments in https://github.com/rust-lang/rustfmt/issues/5623#issuecomment-1334758942. Maybe some of that advice will be useful.

Writing //! # #![rustfmt::skip] to hide the skip attribute is unfortunately not going to work. Rustfmt needs to hack around any lines that start with //! # since they don't parse as valid rust code so internally rustfmt replaces them with a comment before formatting so the #![rustfmt::skip] attribute is never actually seen by rustfmt.

for now I'll link the tracking issue #3348

[max-ishere]

For now I will leave the macro in, I think it may be the easiest solution for a list. I don't actually want to disable all formatting, just in the list so the ```ignore won't work. Also it's a doctest so it would have to be one of the rust code attrs anyway.

[ytmimi]

I think a more complete solution would involve working with the rustdoc team to add an attribute that both tools understand as "rustfmt should skip this, but rustdoc should not".

[max-ishere]

@ytmimi not following with your suggestion...

[max-ishere]

Either way I hope the usecase is clear, mark something as do not format, but hide that marker in the docs. At the moment the nofmt macro is an ok alternative.

[max-ishere]

I think a more complete solution would involve working with the rustdoc team to add an attribute that both tools understand as "rustfmt should skip this, but rustdoc should not".

Oh i see, like ```nofmt. That wont solve my usecase, but could work I guess.

[max-ishere]

And to add to my previous comment, it has to be something you can enable for just one line, because all doc comments are formatted by rustfmt in my project and have some rules like line length 80 I think.