Simplify logic for unindenting doc comments

[camelid]

Related to #65802 (but does not resolve it).

This has almost the same behavior, except that it completely ignores raw
doc comments (i.e., #[doc = "..."]) for the purposes of computing
indentation.

[rustbot]

r? @wesleywiser

rustbot has assigned @wesleywiser.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[camelid]

r? @GuillaumeGomez

[camelid]

We should decide if this change makes sense and also if it could cause stability issues.

[camelid]

I ran a diff of the stdlib docs files between this version and HEAD rustdoc and found no differences.

[GuillaumeGomez]

This change seems surprising, no?

[camelid]

It's strange indeed, especially because (based on the logging I'm looking at), the indent is correctly assessed to be 1. Looking into this more... EDIT: Never mind, that was a different line of code, but still weird.

[camelid]

Ok, so here's the reason. It's because this code is wrapped in a macro (which is just the identity function, returning exactly its input). However, this turns the sugared doc attrs into raw doc attrs; thus, the indent is computed as 0. This also makes the lint's suggestion go into the "uglier" path because source_span_for_markdown_range requires all inputs to be sugared doc attrs.

I don't know if there's something we want to change here. It does seem unfortunate that the indentation rules will change if the docs are passed through a macro, although that does seem like a rare occurrence.

[GuillaumeGomez]

As you prefer then! r=me if it sounds good to you as is. ;)

[GuillaumeGomez]

Apart from the ui test change, looks good to me!

[camelid]

I wonder if we should go through FCP since this changes rustdoc's handling of doc comments? We also should decide if these are truly the rules we want rustdoc to follow for unindenting. E.g., now, if rustdoc sees

///     assert!(true);
fn foo() {}

It will render as

assert!(true);

while previously it would be

assert!(true);

However,

/// Foo
///
///     assert!(true);
fn foo() {}

will render as

Foo

assert!(true);

I think this is a reasonable behavior, the summary being that we take the minimum indentation across all sugar-doc lines and consider that to be the indentation of the whole block. Alternatively, we could use the first line, or we could limit the amount of indentation we take off to be at most 1 space. Thoughts?

@rfcbot merge

[camelid]

@rfcbot merge

[rfcbot]

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

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

No concerns currently listed.

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.

[camelid]

To summarize the new behavior: We only consider sugared doc comments (///, rather than #[doc] or /// that's passed through a macro) when calculating indentation. We pick the least-indented line and remove that amount of indentation from every line coming from sugared doc comments (raw doc comments are left alone).

[GuillaumeGomez]

I don't think removing indent when the only indent present can be formatted as a codeblock is a good idea or a desired behaviour. If the indent is < 4, then I think it's ok, but otherwise it enters in conflict with the markdown spec and I don't think we should do that.

[notriddle]

I'm not sure if we should be changing this. It's trading one weird corner case (I admit it's weird that non-sugared doc comments have indentation stripped) for a different, but equally weird corner case (sugared doc comments passed through macros aren't having their indentation stripped).

The table parsing bug is solved by the newer version of pulldown-cmark. Once we do the upgrade and pulldown-cmark/pulldown-cmark#665 gets deployed in rustdoc, it'll be fixed without having to change this anyway.

[camelid]

I understand. This PR doesn't even fix the table parsing issue. My goal with it was to simplify the logic so we know what exactly we're guaranteeing with respect to unindenting. The current code is somewhat obscure. Instead of making this change, should we discuss what exactly we expect the behavior to be and make sure the code doesn't have edge cases?

@rfcbot cancel

[rfcbot]

@camelid proposal cancelled.