Thanks for reaching out!

You're right, it would definitely be useful to document under what conditions we'll actually run rustfmt on your doc comments. We should probably update the docs for format_code_in_doc_comments to include that information.

That being said, before running rustfmt on the code in your doc comments we first check to see if there are any attributes that would indicate that it's not rust code. We support the rustdoc attributes, and we'll only run rustfmt on the code block if it's annotated with one of "rust", "should_panic", "no_run", "edition2015", "edition2018", "edition2021", or if there are no attributes since we assume that the code block contains rust code in that case.

We'll ignore the code block if it contains any other kind of attribute. For example, "ignore", "compile_fail", or "text".

For some immediate relief to your issue you could write something like this:

/// ```ignore
/// use core::primitive;
///
/// let y = 0;
/// ```
fn main() {}

or even something like this:

/// ```some_random_attribute_so_rustfmt_ignores_the_code
/// use core::primitive;
///
/// let y = 0;
/// ```
fn main() {}

There's definitely an issue when calling crate::format_code_block, as it's adding extra whitespace:

linking tracking issue for format_code_in_doc_comments #3348