Skip to content

Additional docs on pub re-exports resolve intra-doc links relative to the original module #77254

Closed
@jyn514

Description

@jyn514
Member

I tried this code:

/// I want to show [with_code]
pub use std::string::String;

pub fn with_code() {}

I expected to see this happen: Rustdoc links all the original documentation relative to std::string, and all the new documentation relative to the current crate, so with_code resolves properly.

Instead, this happened: Rustdoc links all the original documentation relative to std::string:

Sep 26 22:41:10.388  INFO rustdoc::passes::collect_intra_doc_links: ignoring warning from parent crate: unresolved link to `with_code`

This hits proc-macros especially hard because they're forced to be in a separate crate and can't link to anything in the main crate.

Meta

rustdoc --version: rustdoc 1.48.0-nightly (f68e089 2020-09-19), but also present on master (1ec980d)

Activity

added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
C-bugCategory: This is a bug.
A-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by name
on Sep 27, 2020
added
A-cross-crate-reexportsArea: Documentation that has been re-exported from a different crate
on Sep 27, 2020
jyn514

jyn514 commented on Sep 27, 2020

@jyn514
MemberAuthor

Originally I thought this would need pulldown support, but I might be able to hack it by using the span of the BrokenLink pulldown returns.

jyn514

jyn514 commented on Sep 27, 2020

@jyn514
MemberAuthor

I'm not sure it's possible to go from a Span to the module it's defined in :/

jyn514

jyn514 commented on Sep 27, 2020

@jyn514
MemberAuthor

Another possible approach is to use the DefId of the use statement itself, but that requires fixing #77230 first.

added a commit that references this issue on Sep 27, 2020
jyn514

jyn514 commented on Sep 27, 2020

@jyn514
MemberAuthor

Originally I thought this would need pulldown support, but I might be able to hack it by using the span of the BrokenLink pulldown returns.

It turns out pulldown already has this support in the form of into_offset_iter.

jyn514

jyn514 commented on Oct 4, 2020

@jyn514
MemberAuthor

So I don't forget, this is my current progress:

  • Refactor DocFragments; this was simple and necessary to add the HirId for the docs (Change DocFragments from enum variant fields to structs with a nested enum #77513)
  • Require a HirId for try_inline. This was not too painful but not very useful in itself. It does not currently handle multiple re-exports, I just have an unimplemented!() (not published).
  • Take an optional HirId in merge_attrs. This is necessary but not sufficient for keeping track of the HirId for the attrs.
  • Take an optional HirId in Attributes::from_ast; again, necessary but not sufficient.

The issue I currently have is that attributes are combined before calling from_ast, and I'm not sure how to work merging attrs into from_ast. Maybe it could take attrs: &[ast::Attribute] and other_attrs: &[...], plus a HirId for both? That seems not too painful; I'll need to slightly refactor from_ast to allow doing the same inner actions for two different lists. I have no idea how to generalize this to arbitrary re-exports - maybe Vec<(&[ast::Attribute], HirId)>?

jyn514

jyn514 commented on Oct 4, 2020

@jyn514
MemberAuthor

The painful thing is going to be working this into impl Clean<Attributes> for [ast::Attribute] - Clean doesn't allow taking any additional parameters and turning it into a free function instead causes about 30 non-trivial errors.

jyn514

jyn514 commented on Oct 4, 2020

@jyn514
MemberAuthor

Actually this might work - the original HirId will always correspond to the DefId, so it can just be none. Then any following attributes will make the HirId mandatory. 🤞

jyn514

jyn514 commented on Oct 4, 2020

@jyn514
MemberAuthor

A new problem: collapse_docs turns all attributes into one giant attribute 🤦 @GuillaumeGomez do you know what that's for? Is it safe to just get rid of it and insert newlines between docs instead?

GuillaumeGomez

GuillaumeGomez commented on Oct 4, 2020

@GuillaumeGomez
Member

I think it's to merge both #[doc = "..."] and /// attributes.

added a commit that references this issue on Oct 9, 2020

Auto merge of rust-lang#77519 - jyn514:track-doc-er, r=GuillaumeGomez

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-cross-crate-reexportsArea: Documentation that has been re-exported from a different crateA-intra-doc-linksArea: Intra-doc links, the ability to link to items in docs by nameC-bugCategory: This is a bug.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

      Participants

      @GuillaumeGomez@jyn514

      Issue actions

        Additional docs on pub re-exports resolve intra-doc links relative to the original module · Issue #77254 · rust-lang/rust