Rustdoc issue backlog

[QuietMisdreavus]

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.

• rustdoc: Pain points of reexports #24305

[QuietMisdreavus]

groundwork

• Rustdoc needs to handle conditional compilation somehow #1998
  • the holy grail;
    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 Expose all OS-specific modules in libstd doc. rust-lang/rust#43348 there's a manual escape hatch but it's not automatic
• rustdoc should be able to build documentation from compiled crates #2206
• Inlined documentation loses lifetime parameters on functions #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
    versus in libstd -
    the re-export has dropped the <'a>
• rustdoc’s approach to producing output needs to be rethought #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
  • likely needs a refactor along the lines of 14595's suggestion
• rustdoc: reexported type aliases are not preserved in function signatures #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
  • 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
  • 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
  • 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
  • see also 16103 and 14572
• Use link rel="canonical" to doc.rust-lang.org in HTML docs #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
  • 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
  • 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
  • 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
  • Repeated and incorrect "Implementors" items rust-lang/rust#25061 also contributes to this
• allow line numbers in rustdoc #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
  • 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
  • it's everyone's favorite, another reexport bug! -_-
• Add opensearch support to doc.rust-lang.org #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
  • 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
  • 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
  • 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

[QuietMisdreavus]

legwork

• Treat "Failure" and "Safety note" doc comments specially in generated docs #6759
  • this issue is effectively about wanting to parse common/standard headers and surface them separately in the documentation
  • a good list of standard headers is killercup's post here which also has a link to an old implementation
• List re-exports of a symbol in the documentation for that symbol #13414
  • intra-crate, at least - items get relocated if it's pub used and the original is hidden, and re-exports are
    given a different representation in the clean AST, so it may be possible to just scan it ahead of time to match
    re-exports to a given DefId or the like
  • between crates? that needs groundwork, possibly loads, if you want std's export of things from core to show up in core
• rustdoc doesn't substitute type parameters #14072
  • this is partially there, but check this example
    for where this currently falls short
• rustdoc: provide summary views #14475
  • minor social work to figure out what to put/where to put it, otherwise it's a matter of screaming through all
    the impls/methods to build out the condensed view
• Doc landing page and the 404 page could have the library search box #14572
  • copy the search box and related javascript and put it on an index.html and the 404 page. on std docs this
    can go on the landing page, but for other docs a new index.html is needed
  • "a new index.html" can be considered groundwork if you want to add more things, or social work to get a sense of what
    to put there
• rustdoc: make static functions stand out better #15070
  • doing this within an impl just needs you to pull out functions that don't take self and add some signifier
  • "some signifier" is potential social work (read: a bikeshed waiting to happen) but just putting something
    out there is leagues better than not
• Allow documentation to be read from an external file #15470
  • this is an rfc but once that's sorted it just needs the legwork
    to implement it
• rustdoc: Struct variant fields don't have the right path in the search index #16017
• doc, explicit Result types #16096
  • when type names are collected, keep a count of how many share the same name in their last path segment.
    if there's a clash somewhere, make them print their full path whenever they're printed
• Add settings page to Rustdoc for long-term configuration #18167
  • may be considered groundwork, but since this wouldn't have to touch stuff outside its own world (i.e. you don't have to touch
    the compiler, or even write rust code, for this) i wrote it in this list
  • imo if you can just get something running people would appreciate it, nearly regardless of what form it takes
• Consider indicating which code blocks are expected to compile and which are not in the guide(s) #20524
  • setting aside the social impact of making sure bad code blocks are signalled more clearly, this involved looking for
    compile_fail examples, and... wrapping them in another class? doing something to the blocks to add the desired signals
• Headline Level in API Doc Comments #20863
  • the html for the individual elements are scattered across a ton of display impls and methods in html/format.rs and html/format.rs
  • effectively you'd need to replace all the h2/h3/h4/etc with h1 and change the divs that outline the sections into section/article tags like the issue shows - and edit the css to match
  • testing would be necessary to not run afoul of Tiered browser support policy for Rust's web content rust-lang/rfcs#1985
• Improve docs rendering performance by addressing PageSpeed Insights issues #20962
  • it looks like there's a tool to run on a given page to diagnose potential issues
  • the main page template is in html/layout.rs, tho some pieces may need to happen in each page output, i.e. the item_* functions in html/render.rs
  • possible groundwork, if you want to put a css/js minifier into rustdoc itself?
  • also note that some changes may need to go into mdbook, instead of/in addition to rustdoc
• fn main in a comment in rustdoc breaks tests #21299
  • i made a clarifying comment pointing out which line to change and officially offered to mentor
• Public items re-exported publicly in the same crate could have inlined docs #22310
  • i posted a summary comment, you can tag exports with #[doc(inline)] to inline their docs, but we may want to also put re-exports into the search index
• Include page title in the API search result #24062
  • involves putting the "Module"/"Struct"/"Enum"/etc into the titles shown in the search results when searching
  • probably need to mess with the search index? maybe just the search display?
• Show library version in documentation generated by rustdoc #24336
  • i put this in this list because of the hint described in Insert package name/version in API docs rust-lang/cargo#1681 (comment)
  • a quick implementation would check for the environment variable set by cargo, and then place that version... somewhere >_>
  • possible social work/bikeshedding around where to put this - just the crate root, every page, specific locations, etc
• rustdoc trait implementations should be collapsible #24483
  • a quick-and-dirty implementation of this would just put a <span class='docblock'> around the impl items of an impl, but this leads to problems with method discovery, as mentioned in thread
  • Gankro's "staged super collapse" suggestion is a bit of groundwork (read: solving Treat "Failure" and "Safety note" doc comments specially in generated docs rust-lang/rust#6759 first) for "collapse examples", a bit of bikeshedding for the exact levels, and maybe some small groundwork for staging out the collapse levels separately
• docs for Traits get duplicated because of different types #24558
  • issue suggests folding up trait impl blocks if it's not the last one, so all that's shown is the impl SomeTrait for SomeType line
  • "Option B" would require groundwork to merge together the related impls?
• Add a cfail mode for doc comments #24565
  • this is halfway there already - there's a compile_fail flag on nightly builds that can match against error code(s), the only thing that's missing is the error text matching
• Rustdoc: "Methods from Deref<Target=T>" ignores U bound #24686
  • i left a summary comment
• Rustdoc considers *const T and *mut T different #24897
  • this effectively requires that the PrimitiveType enum in clean/mod.rs be split into both const and mut versions
  • the problem would come in making sure the primitive docs page for "pointer" doesn't also get split, since there's a 1:1 between those docs and that enum
• Advertise impls of out-of-create traits for third party types with some type parameters set to in-crate types in rustdoc #25264
  • in other words, make impl From<LocalType> for ForeignType show up on LocalType's page
  • where the Cache is being built, it's iterating over all the impls in the crate, and sorting them into a HashMap based on the target type - but this could also look in the generics of the trait, if they exist
• Stack overflow in rustdoc using enum_primitive with a big enum #25295
  • requires investigation: does the bug still exist? what is enum_from_primitive! doing that causes rustdoc to overflow? where is the overflow occurring?
• Rustdoc: pages are being overwritten on the file systems with case-insensetive names #25879
  • either involves checking whether a file exists already when writing it, or doing a case-insensitive comparison against other names in the crate
  • in-thread, nrc offered to mentor, but this was a year ago, so it'd be worth making sure he's still okay with it

[QuietMisdreavus]

social work

• Canonical urls for deduplication of google results in rustdoc #9461
  • needs decision on where to link, if available - for std docs this is workable, but generally the question gets fuzzier
  • after decision, just needs legwork to add the tag to the template and wire up the link to populate it
    (getting the link may need small groundwork, depending on where the link comes from)
• Short doc url don't mention Rust version at all #14466
  • this has an open rfc, putting a "version switcher" is
    part of the legwork on it, and will alleviate this
• rustdoc: Allow customizing the crate list sidebar. #16328
  • need to decide how to specify this, then comes the groundwork of working it in
• rustdoc should escape <> #18419
  • the comment thread suggests implementing a whitelist for certain HTML tags, then escaping the <>
    for everything else
  • the "social work" is to decide on that whitelist; after that it's legwork to add a conversion step when
    text is given to the markdown processor

[QuietMisdreavus]

triage work

• rustdoc could use some LD_LIBRARY_PATH handling cleanup #13983
  • possibly groundwork, especially if you want rustdoc to have both host/target paths available at once?
  • if it's just running tests that needs the target path, it's legwork of (1) pulling that path, and (2) stuffing
    it into the doctest runner
• Rustdoc should indicate variance on lifetime/type parameters #22108
  • so, personally, i get variance confused every time someone brings up the concept by name, so since there's no discussion on the issue (and it was also pre-1.0) i'm not sure what's being requested here >_>
  • possibly groundwork? to pull these rules from the compiler? if not, then just the legwork to display the rules
• Rustdoc output slightly nondeterministic #24473
  • needs some investigation as to whether this is still a thing, and with what
  • things like trait impls are in an arbitrary order right now, but whether that's currently "stable" is another matter

[kzys]

I realized that some of them (e.g. rust-lang/rust#8552 and rust-lang/rust#13444) have been fixed already. How about utilizing GitHub's checkbox notation as like other Rust issues to clarify which issues are still open?

[QuietMisdreavus]

This entire list should be rethought - i never finished it, and as you've seen, i haven't touched it since last year. I think ideally, i'd like to see this replaced with some kind of dashboard that automatically checked the GitHub API so i (or some other dev-tools collaborator) didn't have to keep coming back to it. I'll go in and remove the issues you mentioned, at least.

[kzys]

How about having GitHub milestones? I'm unsure we can use that in this repository to manage rust-lang/rust's issues. We may need to have the milestones on rust-lang/rust itself.
https://help.github.com/articles/about-milestones/