Skip to content

Tracking Issue for intra-doc links in libstd #75080

New issue
New issue
Closed
Closed
Tracking Issue for intra-doc links in libstd#75080
Labels
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsA-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by nameC-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCE-easyCall for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue.E-mentorCall for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

Description

@jyn514
jyn514
opened on Aug 3, 2020

This is a tracking issue for switching libstd to intra-doc links (rust-lang/rfcs#1946, #74430 (comment)).

About tracking issues

Tracking issues are used to record the overall progress of implementation.
They are also uses as hubs connecting to other relevant issues, e.g., bugs or open design questions.
A tracking issue is however not meant for large scale discussion, questions, or bug reports about a feature.
Instead, open a dedicated issue for the specific matter and add the relevant feature gate label.

Mentoring instructions (or rather, suggested workflow)

Please first leave a comment here stating that you want to work on file xxx.rs or module xxx, to make sure that this implements Sync.

  1. For each link of the form
[`Type`]: ../../std/module/kind.Name.html#method.foo

rewrite it as

[`Type`]: std::module::Name::foo

In most cases, the type will already be in scope, in which case you can remove the reference link altogether.
For an example PR, see #74470.

  1. Run x.py doc library/std. This should warn(broken_intra_doc_links) by default.
  2. Fix any warnings that appear.
  3. Once you are ready to make a PR, run ./x.py tidy, which will run rustfmt.

In case of rustdoc bugs, there may be broken links that didn't show up when you ran x.py doc. However, these will be caught by the test suite, so you don't have to check them locally.

Suggested tools

Caveats

Primitives that have the same name as a module in scope must use type@ to disambiguate them. For example, to link to char from std, use type@char. This was changed in #75318, char will now link to the primitive, not the module.

The following cannot use intra-doc links. If you run into an issue with them, it's ok to skip them. However, if you see an issue not mentioned here, please file a bug report!

TODO list

This list was generated with rg '\[.*\]: \.\./.*' library/ -l | sed 's/^/- [ ] /' and may not be complete. If you see other links not mentioned here, feel free to fix them as well.

Since most files only have a few links, it's fine to claim multiple files at the same time.

Unclaimed

In-progress

Completed

Cannot be fixed

The following links cannot yet be fixed due to limitations in rustdoc.

Activity

  1. Imagejyn514
    added
    E-easyCall for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue.
    T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
    C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFC
    A-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by name
    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
    E-mentorCall for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion.
    on Aug 3, 2020

  2. denisvasilik commented on Aug 3, 2020

    @denisvasilik
    denisvasilik
    on Aug 3, 2020
    Contributor

    Hi @jyn514, I would like to work on the following files:

    • library/core/src/time.rs
    • library/core/src/cmp.rs
    • library/core/src/borrow.rs

  3. Manishearth commented on Aug 3, 2020

    @Manishearth
    Manishearth
    on Aug 3, 2020
    Member

    Go for it!

  4. RDambrosio016 commented on Aug 4, 2020

    @RDambrosio016
    RDambrosio016
    on Aug 4, 2020
    Contributor

    Many of these links can be brute force replaced using a regex, for items such as ... ../../std/stuff/something.Item.html it can be brute forced with (\[.*\]: )\.\.\/\.\.\/std\/(\w*)\/(\w*)\.(\w*)\.html[^#], then replacing with $1std::$2::$4\n, many more like method ones can also be knocked out using regex replacement, that regex alone can knock out 384 links. So that might be something worth exploring so less work has to be done with replacing boring links like these

  5. RDambrosio016 commented on Aug 4, 2020

    @RDambrosio016
    RDambrosio016
    on Aug 4, 2020
    Contributor

    Method links and others (207) can be caught with (\[.*\]: )\.\.\/\.\.\/std\/(\w*)\/(\w*)\.(\w*)\.html#\w+\.(\w*) and replaced with $1std::$2::$4::$5\n, although as pointed out by @jyn514, some of these are broke even if the replacement is correct, so that will have to be checked manually.

  6. RDambrosio016 commented on Aug 4, 2020

    @RDambrosio016
    RDambrosio016
    on Aug 4, 2020
    Contributor

    Intrinsics furthermore has a lot (~80) of special ones which match (\[.*\])\(\.\.\/\.\.\/std\/(\w*)\/(\w*)\/\w*\.(\w*)\.\w+\) which can be replaced with $1(std::$2::$3::$4). There is another small use of this but with ../../std/module/stuff which can be matched with (\[.*\])\(\.\.\/\.\.\/std\/(\w*)\/\w*\.(\w*)\.\w+\) and replaced with $1(std::$2::$3)

  7. Manishearth commented on Aug 4, 2020

    @Manishearth
    Manishearth
    on Aug 4, 2020
    Member

    Go ahead and try the regex approach, if there are conflcits we can try and resolve them.

  8. RDambrosio016 commented on Aug 4, 2020

    @RDambrosio016
    RDambrosio016
    on Aug 4, 2020
    Contributor

    I ran all replacements, then ran ./x.py test src/tools/linkchecker library/std, and there were no warnings. So i assume all of them worked correctly, however from my convo with @jyn514 some should not really work because they are fundamentally broken? so i am not quite sure if that is not the case or if testing is not working for me.

  9. Manishearth commented on Aug 4, 2020

    @Manishearth
    Manishearth
    on Aug 4, 2020
    Member

    I'm not sure which ones you think will be broken.

  10. jyn514 commented on Aug 4, 2020

    @jyn514
    jyn514
    on Aug 4, 2020
    MemberAuthor

    I'm not sure which ones you think will be broken.

    Associated items anywhere other than documenting the associated item itself (#74489)

  11. 210 remaining items

  12. poliorcetics commented on Oct 12, 2020

    @poliorcetics
    poliorcetics
    on Oct 12, 2020
    Contributor

    Will do !

  13. pitaj commented on Oct 15, 2020

    @pitaj
    pitaj
    on Oct 15, 2020
    Contributor

    Are any of the "Unclaimed" things here actually unclaimed?

    I can't find anything with [flush]: Write::flush that still uses the old links. Same with [TcpStream::read]: Read::read and [i32::MAX]. [crate::ptr] looks fixed too?

  14. jyn514 commented on Oct 15, 2020

    @jyn514
    jyn514
    on Oct 15, 2020
    MemberAuthor

    @pitaj yes

    It's a little misleading because I said what they should be in some cases, not what they are. But there are still links that need to be fixed.

  15. pitaj commented on Oct 15, 2020

    @pitaj
    pitaj
    on Oct 15, 2020
    Contributor

    Ah I see! Thanks for clearing that up.

  16. pitaj commented on Oct 16, 2020

    @pitaj
    pitaj
    on Oct 16, 2020
    Contributor

    I'll claim std::io::buffered and core::intrinsics

  17. ImageJohnTitor
    added 2 commits that reference this issue on Nov 6, 2020

    Rollup merge of rust-lang#78006 - pitaj:master, r=jyn514

    0fce4ed

    Rollup merge of rust-lang#78006 - pitaj:master, r=jyn514

    0e71fc7

  18. GroteGnoom commented on Jan 7, 2021

    @GroteGnoom
    GroteGnoom
    on Jan 7, 2021

    Could [std::convert::identity]: crate::convert::identity be removed from the unclaimed list?

    also [TcpStream::read]:
    #78006

    @jyn514

  19. poliorcetics commented on Jan 7, 2021

    @poliorcetics
    poliorcetics
    on Jan 7, 2021
    Contributor

    library/core/src/str/mod.rs has been done in #77875

  20. ImageDylan-DPC-zz
    added a commit that references this issue on Feb 25, 2021

    Rollup merge of rust-lang#75807 - jyn514:num-intra-link, r=poliorcetics

    c9cf922

  21. sjakobi commented on Mar 27, 2021

    @sjakobi
    sjakobi
    on Mar 27, 2021
    Contributor

    Unclaimed

    I can't find any old-style links in in library/core/src/ptr. I'm probably misunderstanding the task description though.

    (And is whatever remains to be done still E-easy?!)

  22. jyn514 commented on Mar 27, 2021

    @jyn514
    jyn514
    on Mar 27, 2021
    MemberAuthor

    I think there are few enough links left to convert it's not useful to have a tracking issue for them.

  23. Imagejyn514
    closed this as completedon Mar 27, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsA-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by nameC-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCE-easyCall for participation: Easy difficulty. Experience needed to fix: Not much. Good first issue.E-mentorCall for participation: This issue has a mentor. Use #t-compiler/help on Zulip for discussion.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions