4 ms·

Hi Steve, I don't have a login on rust-lang yet, but I wanted to add this comment regarding the documentation: The rust-doc auto generated pages are really co

Hi Steve, I don't have a login on rust-lang yet, but I wanted to add this comment regarding the documentation: The rust-doc auto generated pages are really confusing. The sidebar generally fails to show where in the hierarchy of the API docs you are (ideally it would highlight the current page you're looking at in the hierarchy and provide the full hierarchy to give you context), the breadcrumbs don't indicate that they are links, the breadcrumbs indicate the type of the entry to the left rather than the right adding semantic confusion, and long pages tend to not have a TOC meaning you have to either search in the page or know the page structure ahead of time (probably mostly an issue for new users). I feel like those are all simple mechanical issues that could make the auto-generated rust-docs a lot more useful. It'd also be nice to tie non-auto generated docs into a crate's documentation, but I haven't looked into how rustdoc works so I'd guess that's possible but a lot of people don't do it.

steveklabnik 11y ago
Hey there. Thanks! Rustdoc can _certainly_ use way more improvements. Many of the things you've expressed are here: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Ais... I would love to re-write all of Rustdoc, frankly, but haven't been able to. Even just re-doing the HTML/CS/JS would be pretty great, I think. There are never enough hours in the day. As for non-API docs, https://github.com/rust-lang/cargo/issues/739 https://github.com/rust-lang/cargo/issues/739 is the tracking issue. Also great to have, also just needs someone to come along and do it.
- portmanteaufu 11y ago
  I'm not overly familiar with Rustdoc's internals, but I would imagine that traversing type information will become much more straightforward when HIR/MIR become a reality. Is that accurate? If so, maybe that's a something for which it's worth delaying a structural overhaul.
  - steveklabnik 11y ago
    I have no idea how rustdoc works, frankly. Parsers are one of those things that I am irrationally scared to hack on. At some point, I'll get fed up and overcome that, but it hasn't quite gotten there yet...

steveklabnik 11y ago

Hey there. Thanks! Rustdoc can _certainly_ use way more improvements. Many of the things you've expressed are here: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Ais... I would love to re-write all of Rustdoc, frankly, but haven't been able to. Even just re-doing the HTML/CS/JS would be pretty great, I think. There are never enough hours in the day. As for non-API docs, https://github.com/rust-lang/cargo/issues/739 https://github.com/rust-lang/cargo/issues/739 is the tracking issue. Also great to have, also just needs someone to come along and do it.

portmanteaufu 11y ago
I'm not overly familiar with Rustdoc's internals, but I would imagine that traversing type information will become much more straightforward when HIR/MIR become a reality. Is that accurate? If so, maybe that's a something for which it's worth delaying a structural overhaul.
- steveklabnik 11y ago
  I have no idea how rustdoc works, frankly. Parsers are one of those things that I am irrationally scared to hack on. At some point, I'll get fed up and overcome that, but it hasn't quite gotten there yet...