New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rustdoc issue backlog #23

Open
QuietMisdreavus opened this Issue Aug 7, 2017 · 7 comments

Comments

Projects
None yet
2 participants
@QuietMisdreavus
Collaborator

QuietMisdreavus commented Aug 7, 2017

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.

@QuietMisdreavus

This comment has been minimized.

Collaborator

QuietMisdreavus commented Aug 7, 2017

groundwork

@QuietMisdreavus

This comment has been minimized.

Collaborator

QuietMisdreavus commented Aug 7, 2017

legwork

@QuietMisdreavus

This comment has been minimized.

Collaborator

QuietMisdreavus commented Aug 7, 2017

social work

@QuietMisdreavus

This comment has been minimized.

Collaborator

QuietMisdreavus commented Aug 7, 2017

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

This comment has been minimized.

kzys commented Aug 23, 2018

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 comment has been minimized.

Collaborator

QuietMisdreavus commented Aug 23, 2018

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

This comment has been minimized.

kzys commented Sep 1, 2018

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/

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment