rustdoc: Another round of improvements #24396

alexcrichton · 2015-04-14T01:01:25Z

A few final improvements to rustdoc for 1.0:

Improve how rustdoc handles stability
Fix cross-crate macro source links
Improve experience of types inheriting methods through Deref

Some more details can be found in the commits.

Preview

rust-highfive · 2015-04-14T01:01:30Z

r? @pcwalton

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

alexcrichton · 2015-04-14T01:02:18Z

r? @aturon

cc @sfackler, @wycats, @steveklabnik, @bstrie, @tomjakubowski

sfackler · 2015-04-14T02:04:53Z

Yay! It'd be nice to identify deprecated stuff in search results as well.

wycats · 2015-04-14T02:10:01Z

r+ x 1000. It would be useful to get before and after screenshots for rustdoc changes 😄

tomjakubowski · 2015-04-14T03:04:06Z

Wow, fantastic work as always Alex! I love the changes to stability and of course the "Methods from Deref" sections/

killercup · 2015-04-14T08:03:59Z

Wow, those unstable/deprecated boxes are huge! I'd probably make them look a bit less… alerting, e.g. by using a border-size of only 1px and not make the whole text italic. Might be good to add some margin-bottom to them, as well.

Oh, an here are some screenshots, for posterity.

steveklabnik · 2015-04-14T13:57:01Z

I agree that overall this is an improvement, but agree with @killercup that it's a bit big.

alexcrichton · 2015-04-14T17:54:15Z

Yeah I definitely wouldn't slate myself as a graphic designer any time soon!

@wycats you can compare/contrast the current docs to the hosted docs (what I've been doing) for example:

type	old	new
Vec	old	new
old_io	old	new
io	old	new

liigo · 2015-04-15T02:18:47Z

Another great feature's screenshot, thanks to @alexcrichton !
Vec methods from Deref:

aturon · 2015-04-15T02:24:44Z

This is really awesome work, @alexcrichton! The docs are feeling much more polished, and I really like the Deref treatment.

I do agree with others that the unstable/deprecation warnings are a bit too attention-getting. I suspect that some fairly simple changes to the styling could de-emphasize them, and that seems worth doing in this PR.

alexcrichton · 2015-04-15T16:42:25Z

Ok I've pushed a few tweaks to the style (and re-uploaded the docs). I incorporated @killercup's suggestions (thanks!) and also made the font size a little smaller. I do think that it's still a little jarring but much less so than before!

steveklabnik · 2015-04-15T16:45:16Z

👍

killercup · 2015-04-15T17:01:33Z

👍

(The padding on the bottom looks a bit off to me, but that's nothing major. I'd probably set it to 5px 5px 2px or something like that.)

aturon · 2015-04-15T18:22:50Z

Thanks @alexcrichton! The code looks good to me as well, so:

@bors: r+

bors · 2015-04-15T18:22:51Z

📌 Commit cdb1d95 has been approved by aturon

bors · 2015-04-15T20:11:44Z

⌛ Testing commit cdb1d95 with merge 141a48a...

A few final improvements to rustdoc for 1.0: * Improve how rustdoc handles stability * Fix cross-crate macro source links * Improve experience of types inheriting methods through `Deref` Some more details can be found in the commits. [Preview](http://people.mozilla.org/~acrichton/doc/std/)

bors · 2015-04-15T21:05:15Z

💔 Test failed - auto-linux-64-nopt-t

alexcrichton · 2015-04-15T21:13:29Z

@bors: retry

On Wed, Apr 15, 2015 at 2:05 PM, bors notifications@github.com wrote:

[image: 💔] Test failed - auto-linux-64-nopt-t
http://buildbot.rust-lang.org/builders/auto-linux-64-nopt-t/builds/4479

—
Reply to this email directly or view it on GitHub
#24396 (comment).

bors · 2015-04-16T05:30:39Z

☔ The latest upstream changes (presumably #23682) made this pull request unmergeable. Please resolve the merge conflicts.

tamird · 2015-04-16T15:52:46Z

src/librustdoc/clean/mod.rs

+                    attr::Unstable => "unstable".to_string(),
+                    attr::Stable => String::new(),
+                };
+                if s.deprecated_since.len() > 0 {


@alexcrichton if !s.deprecated_since.is_empty() {?

disregard! i hadn't noticed that the conflict is not yet resolved here

This commit is an overhaul to how rustdoc deals with stability of the standard library. The handling has all been revisited with respect to Rust's current approach to stability in terms of implementation as well as the state of the standard library today. The high level changes made were: * Stable items now have no marker by default * Color-based small stability markers have been removed * Module listings now fade out unstable/deprecated items slightly * Trait methods have a separate background color based on stability and also list the reason that they are unstable. * `impl` blocks with stability no longer render at all. This may be re-added once the compiler recognizes stability on `impl` blocks. * `impl` blocks no longer have stability of the methods implemente indicated * The stability summary has been removed Closes rust-lang#15468 Closes rust-lang#21674 Closes rust-lang#24201

The source filename for cross crate macros isn't quite right so the normal generated links are invalid. Closes rust-lang#21311

alexcrichton · 2015-04-16T16:47:02Z

@bors: r=aturon a1378ff

bors · 2015-04-16T17:37:09Z

⌛ Testing commit a1378ff with merge 3eef83e...

bors · 2015-04-16T19:03:50Z

💔 Test failed - auto-linux-64-x-android-t

Whenever a type implements Deref, rustdoc will now add a section to the "methods available" sections for "Methods from Deref<Target=Foo>", listing all the inherent methods of the type `Foo`. Closes rust-lang#19190

alexcrichton · 2015-04-16T20:29:21Z

@bors: r=aturon 71c1b5b

A few final improvements to rustdoc for 1.0: * Improve how rustdoc handles stability * Fix cross-crate macro source links * Improve experience of types inheriting methods through `Deref` Some more details can be found in the commits. [Preview](http://people.mozilla.org/~acrichton/doc/std/)

bors · 2015-04-16T20:34:56Z

⌛ Testing commit 71c1b5b with merge 1014ac4...

bors · 2015-04-16T22:39:18Z

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-32-nopt-t, auto-win-32-opt, auto-win-64-nopt-t, auto-win-64-opt

Stebalien · 2015-04-18T21:57:22Z

Nice. However, IMHO, the Deref docs shouldn't include static methods.

tomjakubowski · 2015-04-18T22:32:08Z

Probably worth filing an issue for that

Stebalien · 2015-04-18T22:52:31Z

@tomjakubowski

Probably worth filing an issue for that

Good point. Done.

SimonSapin · 2015-04-21T08:44:05Z

This is great! Thanks Alex.

Improve experience of types inheriting methods through Deref

The commit message says this is only inherent methods through Deref. Would it make sense to also show methods available through trait implementations on the Deref target?

alexcrichton · 2015-04-21T15:17:23Z

@SimonSapin my thinking was that the target of the Deref impl generally doesn't implement traits that the source itself does not. For example the traits implemented by String and str are almost the same, so I didn't think it was worth it to add a section for "trait implementations available as methods through Deref".

I chose to only inline inherent methods because that's the real benefit of Deref in terms of docs, you get new inherent methods you didn't previously have.

SimonSapin · 2015-04-21T15:19:33Z

Fair enough, especially now that primitive types can have inherent methods and std doesn’t have so many traits.

rust-highfive assigned pcwalton Apr 14, 2015

rust-highfive assigned aturon and unassigned pcwalton Apr 14, 2015

alexcrichton force-pushed the rustdoc2 branch from 0a3e700 to cdb1d95 Compare April 15, 2015 16:41

tamird reviewed Apr 16, 2015
View reviewed changes

alexcrichton added 2 commits April 16, 2015 09:44

rustdoc: Fix cross-crate macro source links

8fb31f7

The source filename for cross crate macros isn't quite right so the normal generated links are invalid. Closes rust-lang#21311

alexcrichton force-pushed the rustdoc2 branch from cdb1d95 to 28801f7 Compare April 16, 2015 16:46

alexcrichton force-pushed the rustdoc2 branch from 28801f7 to a1378ff Compare April 16, 2015 16:46

rustdoc: Inline methods inhereted through Deref

71c1b5b

Whenever a type implements Deref, rustdoc will now add a section to the "methods available" sections for "Methods from Deref<Target=Foo>", listing all the inherent methods of the type `Foo`. Closes rust-lang#19190

alexcrichton force-pushed the rustdoc2 branch from a1378ff to 71c1b5b Compare April 16, 2015 20:29

alexcrichton mentioned this pull request Apr 16, 2015

Rustdoc problem with lifetimes #24503

Closed

bors merged commit 71c1b5b into rust-lang:master Apr 16, 2015

Stebalien mentioned this pull request Apr 18, 2015

Rustdoc inlined Deref impls should not include static methods. #24575

Closed

alexcrichton deleted the rustdoc2 branch April 21, 2015 15:15

Manishearth mentioned this pull request May 20, 2015

Dining philosophers rephrasing #25640

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

rustdoc: Another round of improvements #24396

rustdoc: Another round of improvements #24396

alexcrichton commented Apr 14, 2015

rust-highfive commented Apr 14, 2015

alexcrichton commented Apr 14, 2015

sfackler commented Apr 14, 2015

wycats commented Apr 14, 2015

tomjakubowski commented Apr 14, 2015

killercup commented Apr 14, 2015

steveklabnik commented Apr 14, 2015

alexcrichton commented Apr 14, 2015

liigo commented Apr 15, 2015

aturon commented Apr 15, 2015

alexcrichton commented Apr 15, 2015

steveklabnik commented Apr 15, 2015

killercup commented Apr 15, 2015

aturon commented Apr 15, 2015

bors commented Apr 15, 2015

bors commented Apr 15, 2015

bors commented Apr 15, 2015

alexcrichton commented Apr 15, 2015

bors commented Apr 16, 2015

tamird Apr 16, 2015

tamird Apr 16, 2015

alexcrichton commented Apr 16, 2015

bors commented Apr 16, 2015

bors commented Apr 16, 2015

alexcrichton commented Apr 16, 2015

bors commented Apr 16, 2015

bors commented Apr 16, 2015

Stebalien commented Apr 18, 2015

tomjakubowski commented Apr 18, 2015

Stebalien commented Apr 18, 2015

SimonSapin commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

SimonSapin commented Apr 21, 2015

rustdoc: Another round of improvements #24396

rustdoc: Another round of improvements #24396

Conversation

alexcrichton commented Apr 14, 2015

rust-highfive commented Apr 14, 2015

alexcrichton commented Apr 14, 2015

sfackler commented Apr 14, 2015

wycats commented Apr 14, 2015

tomjakubowski commented Apr 14, 2015

killercup commented Apr 14, 2015

steveklabnik commented Apr 14, 2015

alexcrichton commented Apr 14, 2015

liigo commented Apr 15, 2015

aturon commented Apr 15, 2015

alexcrichton commented Apr 15, 2015

steveklabnik commented Apr 15, 2015

killercup commented Apr 15, 2015

aturon commented Apr 15, 2015

bors commented Apr 15, 2015

bors commented Apr 15, 2015

bors commented Apr 15, 2015

alexcrichton commented Apr 15, 2015

bors commented Apr 16, 2015

tamird Apr 16, 2015

Choose a reason for hiding this comment

tamird Apr 16, 2015

Choose a reason for hiding this comment

alexcrichton commented Apr 16, 2015

bors commented Apr 16, 2015

bors commented Apr 16, 2015

alexcrichton commented Apr 16, 2015

bors commented Apr 16, 2015

bors commented Apr 16, 2015

Stebalien commented Apr 18, 2015

tomjakubowski commented Apr 18, 2015

Stebalien commented Apr 18, 2015

SimonSapin commented Apr 21, 2015

alexcrichton commented Apr 21, 2015

SimonSapin commented Apr 21, 2015