Documentation block comments always become doctests if indented too much

[gThorondorsen]

In a project of mine, I use the following convention for doc comments (indentation is ____):

____/** Short description

____Long description
____ */

When indented by 5 spaces or more (i.e. 4 more than appear after /**), the Long description part starts getting considered as an indented code block, to be tested as Rust code, despite the comment start /** being at the same indentation level. It happens regardless of whether the empty line contains spaces or not.

I ran into this when I started documenting the fields of struct-like variants in an enum.

Is it possible to fully support this style of doc-comments? I suppose that by the time rustdoc sees the documentation, the type of comment (line or block) and its indentation has been forgotten so it cannot be used by a de-indentation procedure. Would it be possible to special-case the first line and de-indent the others more?¹ If block comments cannot be distinguished from line comments, that has the side effect of not considering the following a doctest anymore:

/// Short description
///
///     assert_eq!(2 + 2, 4);

Meta

Possibly-related issues: #59867, #63193, #64162, #88590

I initially discovered the issue on stable version 1.62.1 and confirmed using the playground that it still happens on nightly (1.65.0-nightly, 2022-08-06 2befdef).

Footnotes

1. I seem to remember that Python does this for its doc-strings. ↩

[jyn514]

@gThorondorsen I believe if you add * at the same indent level as the opening *, it has the behavior you want.

Note to the rustdoc team: any change here is a breaking change and should go through an edition.

[GuillaumeGomez]

I'd be in favor of not changing anything as it would very likely make us shift away from the commonmark spec.

[ethanmsl]

This is maddening!

Rust already recommends a codefence (```) for code to interact with doctests.
Use of whitespace in documentation shouldn't trigger CI errors and force cfg flags to be used.

Simply indenting to, for example, draw a math diagram or add some text triggers this.

At the very least having some configuration variable somewhere that allow indentation to not be used for determining what doctest should run on would be excellent.