add readme for librustdoc #48283

QuietMisdreavus · 2018-02-16T23:02:30Z

In the same vein as the other compiler-library readmes, here's one for rustdoc! It's mainly a "how does rustdoc even" blog-post-style writeup, but i wanted to have something in-repo so people could get a sense of what bits did what.

rust-highfive · 2018-02-16T23:02:33Z

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

QuietMisdreavus · 2018-02-16T23:03:58Z

@GuillaumeGomez @steveklabnik Did i miss anything glaringly obvious here? This file kinda sat half-written on my server for a few months, so at some point i just wanted to get something written up so we could have it online.

mark-i-m · 2018-02-17T22:27:47Z

@QuietMisdreavus Could you add/adapt the same for rustc-guide?

Also, I'm guessing this is for current rustdoc, not https://github.com/steveklabnik/rustdoc?

QuietMisdreavus · 2018-02-17T22:44:02Z

@mark-i-m Yeah, i can add this when it gets approved up here. Don't want to go through the same review nits more than once, haha.

Also yes, since the readme is sitting in src/librustdoc, it's describing that code. I wanted it to be like the README.md in src/librustc, where it can be seen alongside the code when browsing on GitHub.

GuillaumeGomez · 2018-02-18T21:18:19Z

Sounds good to me but I'd prefer an english native speaker to give a look before r+.

mark-i-m

Overall, LGTM. I left a few comments about minor nits...

mark-i-m · 2018-02-19T04:00:20Z

src/librustdoc/README.md

+    CSS/JS and landing page are.
+* Most of the HTML printing code is in `html/format.rs` and `html/render.rs`. It's in a bunch of
+  `fmt::Display` implementations and supplementary functions.
+* The types that operates on are defined in `clean/mod.rs`, right next to the custom `Clean` trait


"The types that operates on"

How about:

The types that got Display impls above are defined in...

Ah, I see. Yeah, that's a lot better.

mark-i-m · 2018-02-19T04:06:13Z

src/librustdoc/README.md

+line in the module page.
+
+Back in `clean/mod.rs`, the other major thing that happens here is the special collection of doc
+comments (and basic `#[doc=""]` attributes) into a separate field in the `Attributes` struct from


This sentence is a bit hard to follow.

How about:

The other major thing that happens in clean/mod.rs is the collection of doc comments and #[doc=""] attributes into a separate field of the Attributes struct, present on anything that gets hand-written documentation. This makes it easier to collect this documentation later in the process.

The primary output of this process is a clean::Crate with a tree of Items which describe the publicly-documentable items in the target crate.

These statements weren't that related anyway, so breaking that last one out into its own paragraph makes that explicit.

mark-i-m · 2018-02-19T04:07:48Z

src/librustdoc/README.md

+whitespace to make the document easier on the markdown parser, or drop items that are not public or
+deliberately hidden with `#[doc(hidden)]`. These are all implemented in the `passes/` directory, one
+file per pass. By default, all of these passes are run on a crate, but the ones regarding dropping
+private/hidden items can be bypassed by passing `--document-private-items` to rustdoc.


It would be good to note where the passes are called from so that adding a new pass is easier...

I avoided mentioning the passes explicitly, since we kinda wanted to abandon the concept, but i can leave a note. It's awkward and wrapped up in the plugin interface that we've explicitly deprecated.

Ah, I see... In that case, maybe it would be better to not document that so it is harder to add another pass.

In other words, take out this section entirely? The passes do some fairly important things, so i would be remiss to leave it out. The entry to the passes isn't necessarily difficult, just awkward. Technically each "pass" is a plugin, loaded up at the same time as any dynamically-loaded plugin that could potentially have been given.

rust/src/librustdoc/lib.rs

Lines 583 to 612 in 27a046e

if default_passes {

for name in passes::DEFAULT_PASSES.iter().rev() {

passes.insert(0, name.to_string());

}

}

// Load all plugins/passes into a PluginManager

let path = plugin_path.unwrap_or("/tmp/rustdoc/plugins".to_string());

let mut pm = plugins::PluginManager::new(PathBuf::from(path));

for pass in &passes {

let plugin = match passes::PASSES.iter()

.position(|&(p, ..)| {

p == *pass

}) {

Some(i) => passes::PASSES[i].1,

None => {

error!("unknown pass {}, skipping", *pass);

continue

},

};

pm.add_plugin(plugin);

}

info!("loading plugins...");

for pname in plugins {

pm.load_plugin(pname);

}

// Run everything!

info!("Executing passes/plugins");

let krate = pm.run_plugins(krate);

No, I think we can just leave it as is. Those who need to deal with it can ask for further clarification when they cross that bridge.

mark-i-m · 2018-02-22T05:25:49Z

@GuillaumeGomez r=english-speaker=me

shepmaster · 2018-03-02T22:53:02Z

Everyone likes progress, yeah?

@bors r=@GuillaumeGomez

bors · 2018-03-02T22:53:03Z

📌 Commit 8d893c1 has been approved by @GuillaumeGomez

…GuillaumeGomez

…GuillaumeGomez add readme for librustdoc In the same vein as the other compiler-library readmes, here's one for rustdoc! It's mainly a "how does rustdoc even" blog-post-style writeup, but i wanted to have something in-repo so people could get a sense of what bits did what.

…GuillaumeGomez

…GuillaumeGomez add readme for librustdoc In the same vein as the other compiler-library readmes, here's one for rustdoc! It's mainly a "how does rustdoc even" blog-post-style writeup, but i wanted to have something in-repo so people could get a sense of what bits did what.

Rollup of 8 pull requests - Successful merges: #48283, #48466, #48569, #48629, #48637, #48680, #48513, #48664 - Failed merges:

mark-i-m · 2018-03-04T02:26:27Z

🎉 perhaps it's time to add it to the rustc guide?

add readme for librustdoc

7aca34b

rust-highfive assigned steveklabnik Feb 16, 2018

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 16, 2018

mark-i-m suggested changes Feb 19, 2018

View reviewed changes

review nits

8d893c1

mark-i-m approved these changes Feb 20, 2018

View reviewed changes

mark-i-m mentioned this pull request Feb 23, 2018

Tracking issue for moving to rustc-guide #48478

Closed

10 tasks

nikomatsakis mentioned this pull request Feb 25, 2018

move over the rustc README rust-lang/rustc-dev-guide#2

Closed

19 tasks

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 2, 2018

Manishearth mentioned this pull request Mar 3, 2018

Rollup of 8 pull requests #48687

Closed

kennytm mentioned this pull request Mar 3, 2018

Rollup of 8 pull requests #48694

Merged

bors added a commit that referenced this pull request Mar 3, 2018

Auto merge of #48694 - kennytm:rollup, r=kennytm

e026b59

Rollup of 8 pull requests - Successful merges: #48283, #48466, #48569, #48629, #48637, #48680, #48513, #48664 - Failed merges:

bors merged commit 8d893c1 into rust-lang:master Mar 3, 2018

QuietMisdreavus deleted the rustdoc-readme branch March 4, 2018 02:46

mark-i-m mentioned this pull request Mar 4, 2018

"Navigating the compiler from the outside" rust-lang/rustc-dev-guide#74

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add readme for librustdoc #48283

add readme for librustdoc #48283

QuietMisdreavus commented Feb 16, 2018

rust-highfive commented Feb 16, 2018

QuietMisdreavus commented Feb 16, 2018

mark-i-m commented Feb 17, 2018

QuietMisdreavus commented Feb 17, 2018

GuillaumeGomez commented Feb 18, 2018

mark-i-m left a comment

mark-i-m Feb 19, 2018

QuietMisdreavus Feb 19, 2018

mark-i-m Feb 19, 2018

mark-i-m Feb 19, 2018

QuietMisdreavus Feb 19, 2018

mark-i-m Feb 19, 2018

QuietMisdreavus Feb 19, 2018

mark-i-m Feb 19, 2018

QuietMisdreavus Feb 19, 2018

mark-i-m Feb 19, 2018

mark-i-m commented Feb 22, 2018

shepmaster commented Mar 2, 2018

bors commented Mar 2, 2018

mark-i-m commented Mar 4, 2018

	if default_passes {
	for name in passes::DEFAULT_PASSES.iter().rev() {
	passes.insert(0, name.to_string());
	}
	}

	// Load all plugins/passes into a PluginManager
	let path = plugin_path.unwrap_or("/tmp/rustdoc/plugins".to_string());
	let mut pm = plugins::PluginManager::new(PathBuf::from(path));
	for pass in &passes {
	let plugin = match passes::PASSES.iter()
	.position(\|&(p, ..)\| {
	p == *pass
	}) {
	Some(i) => passes::PASSES[i].1,
	None => {
	error!("unknown pass {}, skipping", *pass);
	continue
	},
	};
	pm.add_plugin(plugin);
	}
	info!("loading plugins...");
	for pname in plugins {
	pm.load_plugin(pname);
	}

	// Run everything!
	info!("Executing passes/plugins");
	let krate = pm.run_plugins(krate);

add readme for librustdoc #48283

add readme for librustdoc #48283

Conversation

QuietMisdreavus commented Feb 16, 2018

rust-highfive commented Feb 16, 2018

QuietMisdreavus commented Feb 16, 2018

mark-i-m commented Feb 17, 2018

QuietMisdreavus commented Feb 17, 2018

GuillaumeGomez commented Feb 18, 2018

mark-i-m left a 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

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

mark-i-m commented Feb 22, 2018

shepmaster commented Mar 2, 2018

bors commented Mar 2, 2018

mark-i-m commented Mar 4, 2018