QuietMisdreavus
commented
7 years ago groundwork
* [Rustdoc needs to handle conditional compilation somehow #1998](https://github.com/rust-lang/rust/issues/1998)
* [the holy grail](https://github.com/rust-lang/rust/issues/1998#issuecomment-318800909);
needs a lot of far-reaching structural work, or an independent reimplementation of a lot of stuff to sidestep what the compiler does
* thanks to https://github.com/rust-lang/rust/pull/43348 there's a manual escape hatch but it's not automatic
* [rustdoc should be able to build documentation from compiled crates #2206](https://github.com/rust-lang/rust/issues/2206)
* [Inlined documentation loses lifetime parameters on functions #14462](https://github.com/rust-lang/rust/issues/14462)
* another example of inter-crate re-exports being weird - the generics are lost if it just has lifetimes
* for example, `String::from_utf8_lossy` in [libcolllections](https://doc.rust-lang.org/collections/string/struct.String.html#method.from_utf8_lossy)
versus in [libstd](https://doc.rust-lang.org/std/string/struct.String.html#method.from_utf8_lossy) -
the re-export has dropped the `<'a>`
* [rustdoc’s approach to producing output needs to be rethought #14595](https://github.com/rust-lang/rust/issues/14595)
* it's asking to rework the doc process to do passes over all the deps being loaded at once so you can smash all the
metadata together; this is a sizeable refactor/rewrite, to process a dep tree instead of a single crate
* but hey, if this works out you get the bonus request in 13414 taken care of
* [rustdoc: do something about reexported items #15723](https://github.com/rust-lang/rust/issues/15723)
* likely needs a refactor along the lines of 14595's suggestion
* [rustdoc: reexported type aliases are not preserved in function signatures #15823](https://github.com/rust-lang/rust/issues/15823)
* i say groundwork because this is likely the fault ofnthe reexport, rather than rustdoc
* if the export shows up as a type alias and we're just scrubbing it in the import, then
it needs less groundwork
* [Rustdoc could (have an option to) create a top-level index page #16103](https://github.com/rust-lang/rust/issues/16103)
* here's the groundwork portion of 14572
* tbh, this is mostly legwork of putting the template together and making sure std's index stays
* [rustdoc needs a way to specify HTML metadata for standalone docs #16178](https://github.com/rust-lang/rust/issues/16178)
* only "groundwork" per se because of the inclusion of the front matter
* on the other hand, if you can pull all the metadata from the crate itself (not Cargo.toml, tho) then no groundwork needed
* the commonmark switch may have clobbered any hope of porting the canceled PR linked in-thread as-is
* [Rustdoc should show which marker traits a type implements #17606](https://github.com/rust-lang/rust/issues/17606)
* rustdoc needs to be able to tap into the OIBIT/auto trait stuff that the compiler uses
* "marker traits" are fine if they need to be impl'd manually (see: Copy) but auto traits aren't picked up at all
* in 33772 imperio (@GuillaumeGomez) picked up the issue from a different angle, but this may be simpler than that one
* i started working on this one, but stopped when i was faced with issues picking things up from a re-exported module. i still have the branch kicking around if someone wants to pick this up
* [Add a dedicated search page to Rustdoc #18168](https://github.com/rust-lang/rust/issues/18168)
* see also 16103 and 14572
* [Use link rel="canonical" to doc.rust-lang.org in HTML docs #18558](https://github.com/rust-lang/rust/issues/18558)
* this is asking to put canonical links into rustup's rust-src distributions? needs connection with other teams
* ["Ghost" methods in rustdoc for cross-crate trait impls #18717](https://github.com/rust-lang/rust/issues/18717)
* when a trait is impl'd on an external type, its methods show up in the search index, attached to that type
* so fixing this involves rummaging with the search index to recognize when an impl is on a foreign type? may require finesse
to check for things *outside the doc bundle* rather than merely *outside the current crate*
* [rustdoc: provide a way to override html_root_url #19603](https://github.com/rust-lang/rust/issues/19603)
* this is about setting the url prefix for e.g. std/core stuff when linked to from other crate docs
* comment suggests tagging it onto the `extern crate` statement, but this doesn't work for std, which is what the issue
was about in the first place
* may require shenanigans involving command-line flags, which may also extend to shenanigans with cargo
* [Rustdoc links to std library types can bypass the facade #22083](https://github.com/rust-lang/rust/issues/22083)
* this component is mainly about non-std crates that have some implementation on something in std - it will link to the original crate it's in, e.g. alloc/collections/std_unicode
* https://github.com/rust-lang/rust/issues/25061 also contributes to this
* [allow line numbers in rustdoc #22878](https://github.com/rust-lang/rust/issues/22878)
* there may be a setting in hoedown/pulldown to put line numbers in code blocks, there may be some plugin, and if so this is more legwork than groundwork; i dunno for sure, tho
* [rustdoc links to private structs, causing 404s #23912](https://github.com/rust-lang/rust/issues/23912)
* i left a comment, but this manifests today by having rustdoc link to types in deps that aren't being documented alongside the crate itself
* [rustdoc: Self: Sized bounds are pruned #24183](https://github.com/rust-lang/rust/issues/24183)
* it's everyone's favorite, another reexport bug! `-_-`
* [Add opensearch support to doc.rust-lang.org #24899](https://github.com/rust-lang/rust/issues/24899)
* in simplest form, this probably involves adding some new `#[doc]` attribute parameters that control generating an XML file that gets made alongside the rest of the docs
* i'm not too sure that's all that requires tho `>_>`
* [Repeated and incorrect "Implementors" items #25061](https://github.com/rust-lang/rust/issues/25061)
* it's not as egregious today as it was when this was filed, but it's still a thing, and guess what, it's another re-export bug! `-_-`
* figuring out how to get the implementors js file to not get pulled in on a re-export would solve this, i think?
* [Add id values to rustdoc source view for convenient linking #25189](https://github.com/rust-lang/rust/issues/25189)
* all the source highlighting happens in html/highlight.rs
* problem: currently, the highlighting passes the source to the rustc lexer, to figure out the necessary css class to apply to given tokens
* to get semantic info like this would require, you'd need to go further into the compilation process to get things like "this is a name as part of a struct definition" rather than "this is a keyword" which is all you get right now
* inline doc code highlighting also goes through the same code, so you'd need to introduce a signal like "add the ids here" to make sure it didn't add these to all the code blocks in regular documentation, just the source pages
* [Rustdoc: No mention of copy trait for primitive types #25893](https://github.com/rust-lang/rust/issues/25893)
* most primitives have Copy automatically implemented by the compiler, rather than libcore, so these impls don't show up in rustdoc
* pages like tuple/array/fn call this out, but the numbers don't - a "quick" fix would be to add this to the docs for each of them, but it doesn't address that it won't appear in the "Trait Implementations"
* a "full" fix involves checking each primitive against any known marker traits as the page is rendered, or at least against Copy/Send/Sync specifically
kzys
the Great Big List of rustdoc issues (incomplete; last updated 2017-09-08)
It's no secret that rustdoc needs some love. In terms of Area-based issue tags, A-rustdoc is second only to A-diagnostics for "most open issues". (At least, at time of writing, which is 2017-08-07.) I'd like to work through them from oldest to newest, categorizing them based on how much work they require. I'll include some notes about what i think a given issue needs, based on what i know of rustdoc, and from the existing discussion in the thread.
Issues that require groundwork are those that either need to pull some extra information from the compiler, or generate some brand new information, or restructure the code somehow, or some similar amount of "new work" or refactoring. Sometimes this is just another way to frame a small hurdle, sometimes this is a major roadblock that needs coordination from lots of contributors.
Issues that require legwork are mainly about connecting dots that are already there. Usually these are about printing more information, or adjusting some formatting, or some similarly "minor" work.
Issues that require social work need consensus on something. This may involve an RFC, or just a quick canvassing of the relevant teams or the community at large. Usually if i put something in this category i have a decent idea of what other kind of work is required once consensus is reached, so i'll note that in the triage notes.
Finally, issues that need triage work need more information from the OP, or from a source that isn't me. They're either just vague enough that i haven't seen the precise request, or need to touch on something i'm not that familiar with. If you know how to refine this information, or how to fill a knowledge gap, please let me know so i can re-categorize them!
If you want to work on any of these and want some tips, please let me or any of the other rustdoc peers (@steveklabnik and @GuillaumeGomez) know! We're on IRC in #rust-dev-tools and #rust-docs if you want something a little more synchronous.
(shortcut link to issues i haven't written up here)
metabugs
Any existing "list of related issues" pages can just go in this list.