This looks really great. Some random feedback from a skim.
I love that there are cross-references within the code snippets. It's great to be able to quickly look up what a trait means. I noticed that "prelude" in the discussion on http://seld.be/rustdoc/master/std/index.html isn't a link, is that easy to make work or is it too Javadoc-y to need to mark up cross references in free text like that? Speaking of the prelude, I noticed that these docs, like the old rust docs, don't say anything in the prelude. Is that possible to fix? That was one of the first places I wanted to skim when I was trying to get a handle on the language. The relative weights of fonts on the page don't correspond to their importance. That is, the "TUTORIAL | MANUAL" bit is the largest, boldest, most whitespaced piece of the page but they're only links you're really looking for when you first open the docs, not something you need at the forefront when you're digging into the details of some random function. ' This is vague, I feel like there's too many clicks to get into the details of something. E.g. if I'm trying to see what the std module offers, the overview page just lists modules without any description. if I click into ascii, I see a list of functions but I need to click on each one to see what it does. In the golang world they have a convention of providing short summary docs separate from the detailed docs to avoid this; see http://golang.org/pkg/ . I often use ctl-F on that page to find what I'm looking for. Similarly if you click in to a package there -- they show the function types inline which is often a hint to their behavior. You could make the links to source more stable by linking to exactly the version of the source that the docs were built from. E.g. rather than having http://seld.be/rustdoc/master/std/either/fn.lefts.html link to https://github.com/mozilla/rust/blob/master/src/libstd/either.rs#L121-130 you could replace 'master' there with the commit, like https://github.com/mozilla/rust/blob/fad7857c7b2c42da6081e593ab92d03d88643c81/src/libstd/either.rs#L121-130 Consider using the 'title' attribute on links to make the tooltip give some hint about their other side. For example you could embed the short description there. On Mon, Aug 12, 2013 at 8:33 AM, Corey Richardson <co...@octayn.net> wrote: > Hello all, > > I present to you: rustdoc_ng http://seld.be/rustdoc/master/index.html > > It's basically done, only a few minor bugs remain, as well as the > listing of `pub use`'s. I've been using it as my only doc browser the > past day and it's quite wonderful. > > The search is still a bit primitive, but that's not a blocker. So, > give it a spin. Report any bugs either in reply here, or in IRC in > either #rust or #rustdoc-wg. > > Super thanks to Jed Estep and Huon Wilson, who helped a lot with the > backend. And, of course, this would have taken 3x longer and the > result would have been half as good if it were not for Jordi Boggiano > and his amazing work with the web frontend. > _______________________________________________ > Rust-dev mailing list > Rust-dev@mozilla.org > https://mail.mozilla.org/listinfo/rust-dev >
_______________________________________________ Rust-dev mailing list Rust-dev@mozilla.org https://mail.mozilla.org/listinfo/rust-dev
