rustdoc: make impls less noisy

[emberian]

Rendered form available at http://docs.octayn.net/doc/

This moves derived impls to the bottom of the list, separate from the rest,
and collapses default methods that aren't overridden into an expandible
accordion.

[huonw]

Cool!

I think you forgot to upload the std docs? (I get a 404 error clicking on the main link.)

Also, the default method sections have a scroll bar always for me, and, there seems to be a section given even for traits without default methods, example of both: http://docs.octayn.net/doc/rand/struct.XorShiftRng.html

[emberian]

They were uploading (ever so slowly); everything is there now. I seem to
have the scrollbar too, but I don't know what if anything can be done to
fix that. I will fix the no-default-methods case though.

On Sun, Mar 16, 2014 at 11:00 PM, Huon Wilson [email protected]:

Cool!

I think you forgot to upload the std docs? (I get a 404 error clicking on
the main link.)

Also, the default method sections have a scroll bar always for me, and,
there seems to be a section given even for traits without default methods,
example of both: http://docs.octayn.net/doc/rand/struct.XorShiftRng.html

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37781639
.

http://octayn.net/

[sfackler]

DEFAULT METHODS OMITTED; CLICK TO EXPAND.

WHY ARE WE YELLING?

[alexcrichton]

I'm a little uncomfortable pulling in all of jquery-ui for this one use case. The style doesn't quite match the rest of rustdoc (including the fonts), and it seems a little too fancy for what we've got going on.

I think I would also prefer a concise description of methods (like in a trait definition) rather than completely omitting them. I feel like it's the documentation which is taking up the most space.

[emberian]

This isn't all of jquery-ui. It's a custom version that only contains the
code required for the accordion.

On Sun, Mar 16, 2014 at 11:26 PM, Alex Crichton [email protected]:

I'm a little uncomfortable pulling in all of jquery-ui for this one use
case. The style doesn't quite match the rest of rustdoc (including the
fonts), and it seems a little too fancy for what we've got going on.

I think I would also prefer a concise description of methods (like in a
trait definition) rather than completely omitting them. I feel like it's
the documentation which is taking up the most space.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37782473
.

http://octayn.net/

[emberian]

I'm not a webdev so anything else is going to need someone else to do.
Ultimately I think an accordion-like interface is the correct thing.
They're still clutter, even if it's less clutter with just the descriptions.

On Sun, Mar 16, 2014 at 11:27 PM, Corey Richardson [email protected] wrote:

This isn't all of jquery-ui. It's a custom version that only contains
the code required for the accordion.

On Sun, Mar 16, 2014 at 11:26 PM, Alex Crichton [email protected]:

I'm a little uncomfortable pulling in all of jquery-ui for this one use
case. The style doesn't quite match the rest of rustdoc (including the
fonts), and it seems a little too fancy for what we've got going on.

I think I would also prefer a concise description of methods (like in a
trait definition) rather than completely omitting them. I feel like it's
the documentation which is taking up the most space.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37782473
.

http://octayn.net/

http://octayn.net/

[emberian]

The style is also easy to fix... I'm using the same font that non-headers
do, because I felt the default header font was far, far too heavy.

On Sun, Mar 16, 2014 at 11:28 PM, Corey Richardson [email protected] wrote:

I'm not a webdev so anything else is going to need someone else to do.
Ultimately I think an accordion-like interface is the correct thing.
They're still clutter, even if it's less clutter with just the descriptions.

On Sun, Mar 16, 2014 at 11:27 PM, Corey Richardson [email protected]:

This isn't all of jquery-ui. It's a custom version that only contains
the code required for the accordion.

On Sun, Mar 16, 2014 at 11:26 PM, Alex Crichton <[email protected]

wrote:

I'm a little uncomfortable pulling in all of jquery-ui for this one use
case. The style doesn't quite match the rest of rustdoc (including the
fonts), and it seems a little too fancy for what we've got going on.

I think I would also prefer a concise description of methods (like in a
trait definition) rather than completely omitting them. I feel like it's
the documentation which is taking up the most space.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37782473
.

http://octayn.net/

http://octayn.net/

http://octayn.net/

[huonw]

An accordion does make it harder to ctrl-f for some method on a single page.

[emberian]

Hm, I also don't know how it interacts with the doc search. Something
smarter is probably needed here. But I think that our docs are currently
cluttered and hard to read because of the abundance of information on a
single page.

On Sun, Mar 16, 2014 at 11:30 PM, Huon Wilson [email protected]:

An accordion does make it harder to ctrl-f for some method on a single
page.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37782607
.

http://octayn.net/

[alexcrichton]

I would prefer only collapsing the documentation for each individual method, another mild problem is that links like http://docs.octayn.net/doc/std/io/struct.ChanReader.html#method.read_le_u16 no longer work (linking to a default method)

[emberian]

It looks like default methods aren't even in the search index, which is
slightly unfortunate.

On Sun, Mar 16, 2014 at 11:32 PM, Corey Richardson [email protected] wrote:

Hm, I also don't know how it interacts with the doc search. Something
smarter is probably needed here. But I think that our docs are currently
cluttered and hard to read because of the abundance of information on a
single page.

On Sun, Mar 16, 2014 at 11:30 PM, Huon Wilson [email protected]:

An accordion does make it harder to ctrl-f for some method on a single
page.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37782607
.

http://octayn.net/

http://octayn.net/

[emberian]

Indeed. I accidentally had collapsing for each method originally (due to
misreading the api docs), and it wasn't that bad.

On Sun, Mar 16, 2014 at 11:35 PM, Alex Crichton [email protected]:

I would prefer only collapsing the documentation for each individual
method, another mild problem is that links like
http://docs.octayn.net/doc/std/io/struct.ChanReader.html#method.read_le_u16no longer work (linking to a default method)

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37782788
.

http://octayn.net/

[huonw]

#11991 (comment) is another solution that would help: just omit inherited documentation from signatures. (I guess we could have it expandable rather than completely omitted, as you suggest.)

[emberian]

I'm mostly happy with the collapsing now, but the style is still jarring. The signatures look wrong and, when expanded, the background is an ugly white. Not too sure how to fix.

[emberian]

(The only up-to-date rendered docs will be at
http://docs.octayn.net/doc/std/)

On Sun, Mar 16, 2014 at 11:43 PM, Huon Wilson [email protected]:

#11991 (comment)#11991 (comment) another solution that would help: just omit inherited documentation from
signatures. (I guess we could have it expandable rather than completely
omitted.)

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37783029
.

http://octayn.net/

[alexcrichton]

I don't think jquery-ui should be used for this, it's too orthogonal to the rest of the design of rustdoc. All this needs to do is add style:hidden or remove it from the divs with documentation. I don't think that we need fancy animations, the rest of rustdoc isn't all that fancy.

[lifthrasiir]

The accordion seems to misbehave when the inherited method does not have a documentation. (Example)

[emberian]

I'll roll an expando tomorrow.

On Mon, Mar 17, 2014 at 12:17 AM, Kang Seonghoon
[email protected]:

The accordion seems to misbehave when the inherited method does not have a
documentation. (Examplehttp://docs.octayn.net/doc/std/vec_ng/struct.Vec.html#method.le
)

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/12961#issuecomment-37784061
.

http://octayn.net/

[alexcrichton]

@cmr, the current three commits in this PR I think are great to merge. Perhaps they could be rebased on the noise level of the docs could be reduced later?

[emberian]

@alexcrichton ah sorry, there had been a bunch of discussion in irc about reducing noise and it wasn't clear this was desirable. rebased.

[emberian]

@alexcrichton review addressed