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.

Sign up for GitHub

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

Jump to bottom

cargo doc --no-deps shows rustdoc warnings in dependencies #59367

Closed
najamelan opened this issue Mar 22, 2019 · 8 comments
Closed

cargo doc --no-deps shows rustdoc warnings in dependencies #59367

najamelan opened this issue Mar 22, 2019 · 8 comments
Assignees
@GuillaumeGomez
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. E-needs-mcve Call for participation: This issue has a repro, but needs a Minimal Complete and Verifiable Example T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@najamelan
Copy link
Contributor

cargo 1.35.0-nightly (0e35bd8af 2019-03-13)

When running cargo doc --no-deps, dependencies docs are still being checked even if not linked into the resulting documentation. This makes it impossible to generate documentation for my crate if I have deny( warnings ) on. I suppose it would also make it impossible for people depending on my crate to generate documentation if I had deny( warnings ) on.

In other words, it makes it impossible to use deny( warnings ) in published code.
@jonas-schievink jonas-schievink added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-bug Category: This is a bug. labels Mar 22, 2019
@GuillaumeGomez
Copy link
Member

Fix the dependencies? Joke aside, it needs to be fixed. I'll take a look.

@GuillaumeGomez GuillaumeGomez self-assigned this Mar 25, 2019
@najamelan
Copy link
Contributor Author

From this output it clearly happens also if the deny_warnings is in the dependency, but it looks like rustdoc makes a difference in behavior depending on whether it's a path dependency or a crates dependency:

 Documenting tokio v0.1.18
 Documenting tokio v0.1.18 (/data/doc/code/tokio/tokio)
 Documenting serde_cbor v0.9.0
error: `[throttle]` cannot be resolved, ignoring it...
  --> /data/doc/code/tokio/tokio/src/util/stream.rs:13:48
   |
13 | /// Currently, there are only [`timeout`] and [`throttle`] functions, but
   |                                                ^^^^^^^^^^ cannot be resolved, ignoring
   |
note: lint level defined here
  --> /data/doc/code/tokio/tokio/src/lib.rs:2:23
   |
2  | #![deny(missing_docs, warnings, missing_debug_implementations)]
   |                       ^^^^^^^^
   = note: #[deny(intra_doc_link_resolution_failure)] implied by #[deny(warnings)]
   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

error: `[throttle]` cannot be resolved, ignoring it...
  --> /data/doc/code/tokio/tokio/src/util/stream.rs:13:48
   |
13 | /// Currently, there are only [`timeout`] and [`throttle`] functions, but
   |                                                ^^^^^^^^^^ cannot be resolved, ignoring
   |
   = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

error: aborting due to 2 previous errors

error: Could not document `tokio`.

Caused by:
  process didn't exit successfully: `rustdoc --crate-name tokio /data/doc/code/tokio/tokio/src/lib.rs --color always -o /data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/doc --cfg 'feature="async-await-preview"' --cfg 'feature="bytes"' --cfg 'feature="codec"' --cfg 'feature="default"' --cfg 'feature="fs"' --cfg 'feature="io"' --cfg 'feature="mio"' --cfg 'feature="num_cpus"' --cfg 'feature="reactor"' --cfg 'feature="rt-full"' --cfg 'feature="sync"' --cfg 'feature="tcp"' --cfg 'feature="timer"' --cfg 'feature="tokio-async-await"' --cfg 'feature="tokio-codec"' --cfg 'feature="tokio-current-thread"' --cfg 'feature="tokio-executor"' --cfg 'feature="tokio-fs"' --cfg 'feature="tokio-io"' --cfg 'feature="tokio-reactor"' --cfg 'feature="tokio-sync"' --cfg 'feature="tokio-tcp"' --cfg 'feature="tokio-threadpool"' --cfg 'feature="tokio-timer"' --cfg 'feature="tokio-trace-core"' --cfg 'feature="tokio-udp"' --cfg 'feature="tokio-uds"' --cfg 'feature="udp"' --cfg 'feature="uds"' -L dependency=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps --extern bytes=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libbytes-20baa45fbd90af1a.rmeta --extern futures=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libfutures-d7d88decd1b9f95b.rmeta --extern mio=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libmio-a871dfd367e7dc96.rmeta --extern num_cpus=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libnum_cpus-f3ff256cc843f32d.rmeta --extern tokio_async_await=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_async_await-e3e8a0f8c821e5e8.rmeta --extern tokio_codec=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_codec-1b4855f650f293cd.rmeta --extern tokio_current_thread=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_current_thread-814b6491e95f409f.rmeta --extern tokio_executor=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_executor-a0b701715912e0ed.rmeta --extern tokio_fs=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_fs-2eeb9626da53135b.rmeta --extern tokio_io=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_io-481680588c836c91.rmeta --extern tokio_reactor=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_reactor-bb25cedc607922f1.rmeta --extern tokio_sync=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_sync-b633bbfcc90c07e5.rmeta --extern tokio_tcp=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_tcp-98a368eba6ccb1c0.rmeta --extern tokio_threadpool=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_threadpool-2de3cad2cd252e63.rmeta --extern tokio_timer=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_timer-d0620851afb193a3.rmeta --extern tokio_trace_core=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_trace_core-b39affcf5303cc58.rmeta --extern tokio_udp=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_udp-20fa1eeeed6b6d4f.rmeta --extern tokio_uds=/data/doc/code/thespis/thespis_impl/examples/single_thread/remote/target/debug/deps/libtokio_uds-2f0614c7fea4e5be.rmeta` (exit code: 1)
warning: build failed, waiting for other jobs to finish...
error: build failed

I should still verify this, but it looks like a crates version of tokio gets build just before and works, but in the path version it breaks.

@ehuss
Copy link
Contributor

ehuss commented Apr 20, 2019

@najamelan Cargo builds dependencies with --cap-lints=allow unless it is a path dependency. This is done with the intent that these are crates under your control.

I would avoid deny(warnings) for reasons like this.

@najamelan
Copy link
Contributor Author

to follow up on this a bit the deny_warnings issue aside, it still spawns the terminal with warnings from other crates which makes it hard to fix just the warnings in the current crate. I'm trying to fix the warnings in futures-rs if you want to get a feel of what I mean.

Still from running cargo doc --no-deps on futures-rs, master branch with today's nightly. I noticed something else. If it's more appropriate in a different issue, let me know:

warning: `[Error]` cannot be resolved, ignoring it...
    |
    = note: the link appears in this line:
            
            Converts a [`Cow`] into a box of dyn [`Error`] + [`Send`] + [`Sync`].
                                                  ^^^^^^^
    = help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`

A whole bunch of these, with no indication of where they come from. Note the line: = note: the link appears in this line:. The actual line information is missing, so it's not even known in which crate these are. Maybe in std? Note that I have component rust-src installed.

@najamelan
Copy link
Contributor Author

Fix the dependencies? Joke aside, it needs to be fixed. I'll take a look.

Looks more like the false positives need to be fixed...

najamelan added a commit to najamelan/futures-rs that referenced this issue Apr 30, 2019
@najamelan
Attempt to fix all documentation warnings from rustdoc.
0015399 
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 najamelan mentioned this issue Apr 30, 2019
Merged
najamelan added a commit to najamelan/futures-rs that referenced this issue May 5, 2019
@najamelan
Attempt to fix all documentation warnings from rustdoc.
70fcf6d 
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
@najamelan @cramertj
Attempt to fix all documentation warnings from rustdoc.
e4586b5 
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.
@bkchr
Copy link
Contributor

bkchr commented May 11, 2020

@GuillaumeGomez any progress on this?

@bkchr bkchr mentioned this issue May 11, 2020
Merged
@jyn514 jyn514 added the A-intra-doc-links Area: Intra-doc links, the ability to link to items in docs by name label Aug 19, 2020
@jyn514
Copy link
Member

jyn514 commented Aug 19, 2020

I can't reproduce this on current nightly.

$ cargo doc
 Documenting inner v0.1.0 (/home/joshua/test-rustdoc/inner)
    Checking inner v0.1.0 (/home/joshua/test-rustdoc/inner)
warning: unresolved link to `broken`
 --> /home/joshua/test-rustdoc/inner/src/lib.rs:1:11
  |
1 | /// oops [broken] link
  |           ^^^^^^ unresolved link
  |
  = note: `#[warn(intra_doc_link_resolution_failure)]` on by default
  = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`

warning: 1 warning emitted

 Documenting outer v0.1.0 (/home/joshua/test-rustdoc/outer)
    Finished dev [unoptimized + debuginfo] target(s) in 0.97s
$ touch ../inner/src/lib.rs 
$ cargo doc --no-deps
    Checking inner v0.1.0 (/home/joshua/test-rustdoc/inner)
 Documenting outer v0.1.0 (/home/joshua/test-rustdoc/outer)
    Finished dev [unoptimized + debuginfo] target(s) in 0.52s

Are you sure the issue in paritytech/substrate#5923 is related to --no-deps?

@jyn514 jyn514 added the E-needs-mcve Call for participation: This issue has a repro, but needs a Minimal Complete and Verifiable Example label Aug 19, 2020
@jyn514
Copy link
Member

jyn514 commented Aug 29, 2020

I'm going to close this since it looks like it's a duplicate of #56922, which was fixed. Feel free to re-open if you're still having trouble!

@jyn514 jyn514 closed this as completed Aug 29, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@GuillaumeGomez GuillaumeGomez

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. E-needs-mcve Call for participation: This issue has a repro, but needs a Minimal Complete and Verifiable Example T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@ehuss @najamelan @jonas-schievink @GuillaumeGomez @bkchr @jyn514