Write the "passes" chapter of the rustdoc book #43790

steveklabnik · 2017-08-10T20:58:35Z

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 · 2017-08-10T21:47:13Z

src/doc/rustdoc/src/passes.md

+space.
+
+It takes this indentation amount from the first line. For example:


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.

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

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.

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 · 2017-08-10T23:00:54Z

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 · 2017-08-11T14:01:47Z

src/doc/rustdoc/src/passes.md

+```text
+line1
+    line2


this should be:

```text line1 line2 ```

not according to the tests, unless i made a mistake

rust/src/librustdoc/passes/unindent_comments.rs

Lines 127 to 137 in edd82ee

#[test]

fn should_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 · 2017-08-11T14:16:47Z

src/doc/rustdoc/src/passes.md

+## `collapse-docs`
+
+With this pass, multiple `#[doc]` attributes are convered into one single


ollie27 · 2017-08-11T14:20:03Z

src/doc/rustdoc/src/passes.md

+space.
+
+It takes this indentation amount from the first line. For example:


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 · 2017-08-11T19:02:35Z

src/doc/rustdoc/src/passes.md

+```text
+line1
+    line2


Actually, this one would also be:

```text line1 line2 ```

However

```text line1 line2 ```

becomes:

```text line1 line2 ```

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

steveklabnik · 2017-08-14T17:28:58Z

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

durka · 2017-08-14T18:01:38Z

src/doc/rustdoc/src/passes.md

+
+* [`--passes`](command-line-arguments.html#--passes-add-more-rustdoc-passes)
+* [`--no-defaults`](ommand-line-arguments.html#--no-defaults-dont-run-default-passes)


typo in link (missing c)

fixed, thanks

cc rust-lang#42322

QuietMisdreavus · 2017-08-14T21:55:45Z

@bors r+ rollup

❤️

bors · 2017-08-14T21:55:46Z

📌 Commit 7a5ee17 has been approved by QuietMisdreavus

frewsxcv · 2017-08-14T22:39:06Z

src/doc/rustdoc/src/passes.md

+space.
+
+The exact rules are left under-specified so that we can fix issues that we find.


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?

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

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.

…tMisdreavus Write the "passes" chapter of the rustdoc book cc rust-lang#42322 r? @rust-lang/docs

Rollup of 6 pull requests - Successful merges: #43756, #43790, #43846, #43848, #43862, #43868 - Failed merges:

Ship the rustdoc book Fixes #42322, as it's the last step. Blocked on #43790, though they will not conflict. r? @rust-lang/docs

QuietMisdreavus reviewed Aug 10, 2017

View reviewed changes

ollie27 reviewed Aug 11, 2017

View reviewed changes

shepmaster added the S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. label Aug 11, 2017

steveklabnik mentioned this pull request Aug 14, 2017

Ship the rustdoc book #43863

Merged

durka reviewed Aug 14, 2017

View reviewed changes

steveklabnik force-pushed the rustdoc-passes branch from 58c85ae to 4149ad9 Compare August 14, 2017 19:08

Write the "passes" chapter of the rustdoc book

7a5ee17

cc rust-lang#42322

steveklabnik force-pushed the rustdoc-passes branch from 4149ad9 to 7a5ee17 Compare August 14, 2017 19:11

frewsxcv reviewed Aug 14, 2017

View reviewed changes

frewsxcv added a commit to frewsxcv/rust that referenced this pull request Aug 15, 2017

Rollup merge of rust-lang#43790 - steveklabnik:rustdoc-passes, r=Quie…

b1bdf13

…tMisdreavus Write the "passes" chapter of the rustdoc book cc rust-lang#42322 r? @rust-lang/docs

frewsxcv mentioned this pull request Aug 15, 2017

Rollup of 6 pull requests #43872

Merged

bors added a commit that referenced this pull request Aug 15, 2017

Auto merge of #43872 - frewsxcv:rollup, r=frewsxcv

df80627

Rollup of 6 pull requests - Successful merges: #43756, #43790, #43846, #43848, #43862, #43868 - Failed merges:

bors merged commit 7a5ee17 into rust-lang:master Aug 15, 2017

bors added a commit that referenced this pull request Aug 15, 2017

Auto merge of #43863 - steveklabnik:ship-the-rustdoc-book, r=frewsxcv

c774c95

Ship the rustdoc book Fixes #42322, as it's the last step. Blocked on #43790, though they will not conflict. r? @rust-lang/docs

steveklabnik deleted the rustdoc-passes branch October 25, 2017 18:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Write the "passes" chapter of the rustdoc book #43790

Write the "passes" chapter of the rustdoc book #43790

steveklabnik commented Aug 10, 2017

QuietMisdreavus left a comment

QuietMisdreavus Aug 10, 2017 •

edited

Loading

steveklabnik Aug 10, 2017

ollie27 Aug 11, 2017

steveklabnik Aug 11, 2017

steveklabnik commented Aug 10, 2017

ollie27 Aug 11, 2017

steveklabnik Aug 11, 2017 •

edited

Loading

ollie27 Aug 11, 2017

ollie27 Aug 11, 2017

steveklabnik Aug 11, 2017

ollie27 Aug 11, 2017

ollie27 Aug 11, 2017

steveklabnik commented Aug 14, 2017

durka Aug 14, 2017

steveklabnik Aug 14, 2017

QuietMisdreavus commented Aug 14, 2017

bors commented Aug 14, 2017

frewsxcv Aug 14, 2017

frewsxcv Aug 14, 2017

QuietMisdreavus Aug 14, 2017

		space.

		It takes this indentation amount from the first line. For example:

	#[test]
	fn should_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");
	}

		## `collapse-docs`

		With this pass, multiple `#[doc]` attributes are convered into one single


		* [`--passes`](command-line-arguments.html#--passes-add-more-rustdoc-passes)
		* [`--no-defaults`](ommand-line-arguments.html#--no-defaults-dont-run-default-passes)

		space.

		The exact rules are left under-specified so that we can fix issues that we find.

Write the "passes" chapter of the rustdoc book #43790

Write the "passes" chapter of the rustdoc book #43790

Conversation

steveklabnik commented Aug 10, 2017

QuietMisdreavus left a comment

Choose a reason for hiding this comment

QuietMisdreavus Aug 10, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Aug 10, 2017

Choose a reason for hiding this comment

steveklabnik Aug 11, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Aug 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuietMisdreavus commented Aug 14, 2017

bors commented Aug 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuietMisdreavus Aug 10, 2017 •

edited

Loading

steveklabnik Aug 11, 2017 •

edited

Loading