Write the "passes" chapter of the rustdoc book

[steveklabnik]

cc #42322

r? @rust-lang/docs

[QuietMisdreavus]

When #43348 is merged, will you want to add its propagate-doc-cfg pass? It relies on the #[doc(cfg)] attribute form, which will be behind a feature flag when it's first released.

[QuietMisdreavus]

In my experience it takes this indentation amount from the smallest indentation it sees over the whole docstring. This is the entire reason #42760 exists. Putting an example with differently-indented lines like below, but with the order reversed, will demonstrate this.

[steveklabnik]

I took the examples from the tests. Maybe we should add more tests for those cases.

[ollie27]

What it seems to do is take the smallest indent from the whole document but it will ignore the indent on the first line if the second line isn't entirely white-space. It also always removes white-space from the beginning of the first line and doesn't remove anything from lines which are entirely white-space. I'm sure the logic can be improved because there are also #38173 and #38739 which I think are also caused by this.

[steveklabnik]

should we maybe just be more vague about this, rather than going into this level of detail? That way we can tweak it in the future.

[steveklabnik]

When #43348 is merged, will you want to add its propagate-doc-cfg pass? It relies on the #[doc(cfg)] attribute form, which will be behind a feature flag when it's first released.

Hmmm how to handle unstable things is.... something I haven't though of yet.

[ollie27]

this should be:

```textline1line2```

[steveklabnik]

not according to the tests, unless i made a mistake

[ollie27]

rust/src/librustdoc/passes/unindent_comments.rs

Lines 127 to 137 in edd82ee

	#[test]
	fnshould_ignore_first_line_indent(){
	// The first line of the first paragraph may not be indented as
	// far due to the way the doc string was written:
	//
	// #[doc = "Start way over here
	// and continue here"]
	let s = "line1\n line2".to_string();
	let r = unindent(&s);
	assert_eq!(r,"line1\nline2");
	}

[ollie27]

*converted

[steveklabnik]

fixed

[ollie27]

What it seems to do is take the smallest indent from the whole document but it will ignore the indent on the first line if the second line isn't entirely white-space. It also always removes white-space from the beginning of the first line and doesn't remove anything from lines which are entirely white-space. I'm sure the logic can be improved because there are also #38173 and #38739 which I think are also caused by this.

[ollie27]

Actually, this one would also be:

```textline1line2```

However

```text line1 line2```

becomes:

```textline1 line2```

Whether the second line is entirely white-space or not makes a difference.

[steveklabnik]

I've gone with #43790 (comment), this should be ready for review

[durka]

typo in link (missing c)

[steveklabnik]

fixed, thanks

[QuietMisdreavus]

@bors r+ rollup

❤️

[bors]

📌 Commit 7a5ee17 has been approved by QuietMisdreavus

[frewsxcv]

This line confuses me. Is this pass anything more complex than removing a single space if it exists? Are we not able to fix issues if we specify the rules?

[frewsxcv]

Ah, just saw this was approved. Don't block this PR on my comment here, but feel free to answer if there's an answer

[QuietMisdreavus]

The current semantics are a bit awkward to specify completely, see the thread at #43790 (comment) for a brief summary. I think the thought for stating this was that if we describe everything it does then it would create a situation where either we get penned in by the current implementation, or the docs inevitably get out of sync when we patch around various issues.