Skip to content
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 intra-doc links: false positive on trait impls from other crates #55907

Closed
QuietMisdreavus opened this issue Nov 12, 2018 · 3 comments
Closed
Labels
A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@QuietMisdreavus
Copy link
Member

In crate inner:

/// this is a trait
pub trait SomeTrait {
    /// this is a method for [SomeTrait]
    fn qwop();
}

/// this is an impl for [SomeTrait].
impl<T> SomeTrait for T {
    fn qwop() {}
}

Crate outer only needs to link against inner, and since my testbed is set to 2018 it's just the following:

#[doc(no_inline)]
pub use inner;

Building docs for outer will generate false positives for the items in inner: (My testbed uses asdf for outer and qwop for inner, but the message should be the same)

$ cargo +nightly doc
 Documenting asdf v0.1.0 (/home/misdreavus/git/asdf)
warning: `[SomeTrait]` cannot be resolved, ignoring it...
 --> /home/misdreavus/git/asdf/qwop/src/lib.rs:7:26
  |
7 | /// this is an impl for [SomeTrait].
  |                          ^^^^^^^^^ cannot be resolved, ignoring
  |
  = note: #[warn(intra_doc_link_resolution_failure)] on by default
  = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

warning: `[SomeTrait]` cannot be resolved, ignoring it...
 --> /home/misdreavus/git/asdf/qwop/src/lib.rs:3:31
  |
3 |     /// this is a method for [SomeTrait]
  |                               ^^^^^^^^^ cannot be resolved, ignoring
  |
  = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

    Finished dev [unoptimized + debuginfo] target(s) in 2.74s
@QuietMisdreavus QuietMisdreavus added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-synthetic-impls Area: Synthetic impls, used by rustdoc to document auto traits and traits with blanket impls A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name and removed A-synthetic-impls Area: Synthetic impls, used by rustdoc to document auto traits and traits with blanket impls labels Nov 12, 2018
@dhardy
Copy link
Contributor

dhardy commented Jan 25, 2019

Not sure if this is exactly the same issue, but Rand has a lot of false positive "cannot be resolved" warnings (e.g. here).

@najamelan
Copy link
Contributor

Seeing false positives in futures-rs as well:

warning: `[AsyncSeekExt::seek]` cannot be resolved, ignoring it...
 --> futures-util/src/io/seek.rs:7:29
  |
7 | /// Future for the [`seek`](AsyncSeekExt::seek) method.
  |                             ^^^^^^^^^^^^^^^^^^ cannot be resolved, ignoring
  |
  = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

This will generate a correct link, but still warn. Anything else I tried fails to generate a correct link:

::futures::io::AsyncSeekExt::seek
::futures_util::io::AsyncSeekExt::seek
super::AsyncSeekExt::seek <- note that this one does NOT warn but does NOT generate correct link
crate::io::AsyncSeekExt::seek
self::super::AsyncSeekExt::seek

najamelan added a commit to najamelan/futures-rs that referenced this issue Apr 30, 2019
I attempted to fix all documentation warnings in futures-rs. All of these refer to failing cross-
references. Note that it's hard to verify as there is still alot of warnings from dependencies
like rand and from what I suspect to be std, but it's unclear, since rustdoc doesn't mark the
origin of the warnings. See: rust-lang/rust#59367 and rust-lang/rust#55907

The fixes here contain several TODO's, for two main reasons:
- false positive warnings from rustdoc, where rustdoc generates a correct link but still issues
  a warning
- places where I have been obliged to put a link to an html file because I didn't manage to make
  rustdoc generate a correct link from a path.

It would be nice if people verified that commits don't throw warnings before merging,
even in rustdoc. Especially so because rustdoc does not hide warnings in dependencies
right now, even when called with `--no-deps`. That means that any warnings thrown by
futures-rs will bother every single dev that has a (indirect) dependency on futures-rs
and runs rustdoc.
najamelan added a commit to najamelan/futures-rs that referenced this issue May 5, 2019
I attempted to fix all documentation warnings in futures-rs. All of these refer to failing cross-
references. Note that it's hard to verify as there is still alot of warnings from dependencies
like rand and from what I suspect to be std, but it's unclear, since rustdoc doesn't mark the
origin of the warnings. See: rust-lang/rust#59367 and rust-lang/rust#55907

The fixes here contain several TODO's, for two main reasons:
- false positive warnings from rustdoc, where rustdoc generates a correct link but still issues
  a warning
- places where I have been obliged to put a link to an html file because I didn't manage to make
  rustdoc generate a correct link from a path.

It would be nice if people verified that commits don't throw warnings before merging,
even in rustdoc. Especially so because rustdoc does not hide warnings in dependencies
right now, even when called with `--no-deps`. That means that any warnings thrown by
futures-rs will bother every single dev that has a (indirect) dependency on futures-rs
and runs rustdoc.
cramertj pushed a commit to rust-lang/futures-rs that referenced this issue May 6, 2019
I attempted to fix all documentation warnings in futures-rs. All of these refer to failing cross-
references. Note that it's hard to verify as there is still alot of warnings from dependencies
like rand and from what I suspect to be std, but it's unclear, since rustdoc doesn't mark the
origin of the warnings. See: rust-lang/rust#59367 and rust-lang/rust#55907

The fixes here contain several TODO's, for two main reasons:
- false positive warnings from rustdoc, where rustdoc generates a correct link but still issues
  a warning
- places where I have been obliged to put a link to an html file because I didn't manage to make
  rustdoc generate a correct link from a path.

It would be nice if people verified that commits don't throw warnings before merging,
even in rustdoc. Especially so because rustdoc does not hide warnings in dependencies
right now, even when called with `--no-deps`. That means that any warnings thrown by
futures-rs will bother every single dev that has a (indirect) dependency on futures-rs
and runs rustdoc.
@jonas-schievink jonas-schievink added the C-bug Category: This is a bug. label Jul 29, 2019
@jyn514
Copy link
Member

jyn514 commented Aug 19, 2020

This no longer warns on the latest nightly, I expect it's a special case of #65983.

@jyn514 jyn514 closed this as completed Aug 19, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name C-bug Category: This is a bug. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

5 participants