the Great Big List of rustdoc issues

list.md

the Great Big List of rustdoc issues (incomplete; last updated 2017-08-07)

i'm trying to fill this in over time giving an initial impression of what a given issue takes to solve.

last issue categorized: 20524

https://github.com/rust-lang/rust/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3AA-rustdoc%20sort%3Acreated-asc%20created%3A%3E2015-01-04

for tips on how to mess with rustdoc, check out "a whirlwind tour of rustdoc"

table of contents

• groundwork
• legwork
• social work
• triage work

groundwork

(i.e. likely needs structural changes somewhere)

• 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
• 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
• 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

legwork

(i.e. likely just needs someone to connect existing plumbing)

• Treat "Failure" and "Safety note" doc comments specially in generated docs #6759
• Rustdoc shouldn't list modules only alphabetically #8552
  • just rendering modules in declaration-order is a matter of not sorting them and making sure the default order is what you want
  • interspersing headings within the stock modules listing needs groundwork, to have some kind of special doc comment that the compiler will allow and that rustdoc will pick up on while enumerating modules
• 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
• Tests for rustdoc search indices #13444
• 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

social work

(i.e. needs consensus on what even to do, before recategorizing as one of the above)

• 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

triage work

(i.e. requires more explanation for QuietMisdreavus to be able to categorize it >_>)

• 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