Rust: `cargo doc` fails for the h2 crate (v0.1.9) on nightly 2018-06-05
$ rustup show
Default host: x86_64-apple-darwin
installed toolchains
--------------------
stable-x86_64-apple-darwin
nightly-x86_64-apple-darwin (default)
active toolchain
----------------
nightly-x86_64-apple-darwin (default)
rustc 1.28.0-nightly (4a9c58c6b 2018-06-05)
$ cargo doc -p h2
Documenting h2 v0.1.9
warning: [u8] cannot be resolved, ignoring it...
--> /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/bytes-0.4.8/src/lib.rs:1:1
|
1 | / //! Provides abstractions for working with bytes.
2 | | //!
3 | | //! The `bytes` crate provides an efficient byte buffer structure
4 | | //! ([`Bytes`](struct.Bytes.html)) and traits for working with buffer
... |
68 | | //! perform a syscall, which has the potential of failing. Operations on `Buf`
69 | | //! and `BufMut` are infallible.
| |________________________________^
|
= note: the link appears in this line:
A `Bytes` handle can be created directly from an existing byte store (such as &[u8]
^^
warning: [cfg] cannot be resolved, ignoring it...
--> /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/cfg-if-0.1.3/src/lib.rs:1:1
|
1 | / //! A macro for defining #[cfg] if-else statements.
2 | | //!
3 | | //! The macro provided by this crate, `cfg_if`, is similar to the `if/elif` C
4 | | //! preprocessor macro by allowing definition of a cascade of `#[cfg]` cases,
... |
26 | | //! # fn main() {}
27 | | //! ```
| |_______^
|
= note: the link appears in this line:
A macro for defining #[cfg] if-else statements.
^^^
warning: [cfg] cannot be resolved, ignoring it...
--> /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/cfg-if-0.1.3/src/lib.rs:1:1
|
1 | / //! A macro for defining #[cfg] if-else statements.
2 | | //!
3 | | //! The macro provided by this crate, `cfg_if`, is similar to the `if/elif` C
4 | | //! preprocessor macro by allowing definition of a cascade of `#[cfg]` cases,
... |
26 | | //! # fn main() {}
27 | | //! ```
| |_______^
|
= note: the link appears in this line:
This allows you to conveniently provide a long list #[cfg]'d blocks of code
^^^
warning: [Debug] cannot be resolved, ignoring it...
|
= note: the link appears in this line:
themselves through the [`Display`] and [`Debug`] traits, and may provide
^^^^^^^
error[E0658]: access to extern crates through prelude is experimental (see issue #44660)
|
= help: add #![feature(extern_prelude)] to the crate attributes to enable
error: Could not document `h2`.
Caused by:
process didn't exit successfully: `rustdoc --crate-name h2 /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/h2-0.1.9/src/lib.rs -o /Users/example/example-cargo-project/target/doc -L dependency=/Users/example/example-cargo-project/target/debug/deps --extern byteorder=/Users/example/example-cargo-project/target/debug/deps/libbyteorder-df3eee4befa1312c.rmeta --extern bytes=/Users/example/example-cargo-project/target/debug/deps/libbytes-9fc866f4058b4096.rmeta --extern fnv=/Users/example/example-cargo-project/target/debug/deps/libfnv-2278a5d27eb0baf9.rmeta --extern futures=/Users/example/example-cargo-project/target/debug/deps/libfutures-5c1e38662d6f78e5.rmeta --extern http=/Users/example/example-cargo-project/target/debug/deps/libhttp-b2084a070c91801e.rmeta --extern indexmap=/Users/example/example-cargo-project/target/debug/deps/libindexmap-fbca607fdf3e2794.rmeta --extern log=/Users/example/example-cargo-project/target/debug/deps/liblog-1c027577d3857644.rmeta --extern slab=/Users/example/example-cargo-project/target/debug/deps/libslab-4299e706602486cd.rmeta --extern string=/Users/example/example-cargo-project/target/debug/deps/libstring-1c5b00744b69ff86.rmeta --extern tokio_io=/Users/example/example-cargo-project/target/debug/deps/libtokio_io-79182f96ea980954.rmeta` (exit code: 101)
jimmycuadra
All 17 comments
This is a regression from stable to nightly. cc @rust-lang/rustdoc
pietroalbini
on 11 Jun 2018
No it's not, it's a nightly version using a nightly feature (intra-link to exact).
GuillaumeGomez
on 11 Jun 2018
We've been getting enough of these breaking errors out of the intra-links that i wonder if we should introduce a "rustdoc feature flag" for it. Something like #![doc(feature(type_links))]? It would help contain these errors.
The actual compile error is also a duplicate of https://github.com/rust-lang/rust/issues/50561. Everything else is just warnings that lead up to that point.`
QuietMisdreavus
on 11 Jun 2018
Good news: The compile error shown in the issue description was fixed in https://github.com/rust-lang/rust/pull/50617.
Bad news: The h2 crate still can't compile on nightly, because of a #![deny(warnings)] interacting with the new intra-doc-link resolution failure lint:
$ cargo +nightly rustdoc
Documenting h2 v0.1.10 (file:///home/misdreavus/clones/h2)
error: `[u8]` cannot be resolved, ignoring it...
--> /home/misdreavus/.cargo/registry/src/github.com-1ecc6299db9ec823/bytes-0.4.8/src/lib.rs:21:85
|
21 | //! A `Bytes` handle can be created directly from an existing byte store (such as &[u8]
| ^^ cannot be resolved, ignoring
|
note: lint level defined here
--> src/lib.rs:88:9
|
88 | #![deny(warnings, missing_debug_implementations, missing_docs)]
| ^^^^^^^^
= note: #[deny(intra_doc_link_resolution_failure)] implied by #[deny(warnings)]
= help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
error: Could not document `h2`.
I'm not familiar with the h2 crate; is the Bytes publicly exported? If not, then that error will go away with https://github.com/rust-lang/rust/issues/51684.
QuietMisdreavus
on 23 Jun 2018
@QuietMisdreavus Is there an issue somewhere tracking the the resolution of interactions between #![deny(warnings] and rustdoc? Similar to how cargo build works, cargo doc shouldn't fail if upstream dependencies have #![deny(warnings)]-- I'd even argue that denying warnings shouldn't ever cause rustdoc to fail, and that there should be a separate flag for ensuring that documentation doesn't trigger warnings. Do you know if there's been any talk about a "please, really do document these crates to the best of your ability" setting in rustdoc?
cramertj
on 3 Jul 2018
Why should rustdoc overlook lints/warnings/errors? It seems to be problematic from my point of view. Thanks to it, we were able to find errors while documenting the std so I'd say it's a great thing which was missing.
Otherwise I opened a PR to fix the #[deny(warnings)] issue in #51956. Waiting for the compiler team to end discussions about it.
GuillaumeGomez
on 3 Jul 2018
@GuillaumeGomez It's a great thing that rustdoc can issue warnings, but it shouldn't block the creation of docs. For an upstream with #![deny(warnings)], there is no way to generate documentation for it when a new warning is added and the doc generation breaks. This means that users using cargo doc to generate docs for their project and its dependencies will cease to have working docs generation.
cramertj
on 3 Jul 2018
@GuillaumeGomez Because the crate that rustdoc sees is not the same as the crate that rustc sees. Most notably, everybody-loops means that it's quite possible that some imports will become "unused" even if they worked just fine in the original crate.
QuietMisdreavus
on 3 Jul 2018
@cramertj: If it blocks compilation, it should block doc generation.
@QuietMisdreavus: Yes and we need to fix a few things but that's pretty common for new features.
GuillaumeGomez
on 4 Jul 2018
@GuillaumeGomez In my case, it does not block compilation. I can build with my transitive dependency on futures_core just fine, it's only when I try to document my crate with its dependencies that cargo doc fails when trying to document futures_core.
cargo doc worked as of a few weeks ago and is crucially important to me. I would really appreciate it if some solution were found to let it work again.
rtsuk
on 6 Jul 2018
I wonder, now that https://github.com/rust-lang/rust/pull/51732 is landed, whether we can make cargo cap lints to Allow for dependencies when documenting, like it does for compiling? That would sidestep errors like these where the crate really isn't at fault. I just noticed those lint flags were unstable, though...
QuietMisdreavus
on 6 Jul 2018
Once https://github.com/rust-lang/rust/pull/51956 is merged, your problem should be solved.
GuillaumeGomez
on 6 Jul 2018
I am also running into this issue: I upgraded my toolchain to the latest nightly, and suddenly something in a dependency of a dependency of a dependency has now caused my doc generation to break. I will retry tomorrow when the next nightly is published.
dgrnbrg
on 10 Jul 2018
51956 has been merged. I'm not clear if that was expected to fix this problem, because I'm still getting failures to build docs due to #![deny(warnings)] in upstream crates as of nightly 2018-07-13:
$ cargo doc -p net2
Documenting net2 v0.2.31
error: `[cfg]` cannot be resolved, ignoring it...===========> ] 4/5: net2(doc)
--> /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/cfg-if-0.1.2/src/lib.rs:1:28
|
1 | //! A macro for defining #[cfg] if-else statements.
| ^^^ cannot be resolved, ignoring
|
note: lint level defined here
--> /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/net2-0.2.31/src/lib.rs:42:23
|
42| #![deny(missing_docs, warnings)]
| ^^^^^^^^
= note: #[deny(intra_doc_link_resolution_failure)] implied by #[deny(warnings)]
= help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
error: `[cfg]` cannot be resolved, ignoring it...
--> /Users/example/.cargo/registry/src/github.com-1ecc6299db9ec823/cfg-if-0.1.2/src/lib.rs:7:59
|
7 | //! This allows you to conveniently provide a long list #[cfg]'d blocks of code
| ^^^ cannot be resolved, ignoring
|
= help: to escape `[` and `]` characters, just add '\' before them like `\[` or `\]`
error: Could not document `net2`.
Still not working with 2018-07-15, but I found that by setting RUSTDOCFLAGS to "--cap-lints allow -Z unstable-options" I can work around it.
rtsuk
on 16 Jul 2018
Working now?
% rustup show
Default host: x86_64-apple-darwin
installed toolchains
--------------------
stable-x86_64-apple-darwin
nightly-x86_64-apple-darwin (default)
active toolchain
----------------
nightly-x86_64-apple-darwin (default)
rustc 1.30.0-nightly (ae7fe84e8 2018-09-26)
% cargo doc -p net2
Checking libc v0.2.43
Checking cfg-if v0.1.5
Documenting cfg-if v0.1.5
Documenting libc v0.2.43
Documenting net2 v0.2.33
Finished dev [unoptimized + debuginfo] target(s) in 6.60s
% cargo doc -p h2
Checking byteorder v1.2.6
Documenting byteorder v1.2.6
Documenting fnv v1.0.6
Documenting futures v0.1.24
Checking fnv v1.0.6
Checking futures v0.1.24
Documenting itoa v0.4.3
Checking itoa v0.4.3
Documenting slab v0.4.1
Checking indexmap v1.0.1
Documenting string v0.1.1
Documenting indexmap v1.0.1
Checking slab v0.4.1
Checking string v0.1.1
Documenting iovec v0.1.2
Checking iovec v0.1.2
Checking log v0.4.5
Documenting log v0.4.5
Checking bytes v0.4.10
Documenting bytes v0.4.10
Checking tokio-io v0.1.9
Checking http v0.1.13
Documenting http v0.1.13
Documenting tokio-io v0.1.9
Documenting h2 v0.1.12
Finished dev [unoptimized + debuginfo] target(s) in 15.75s
%
kzys
on 27 Sep 2018
Seems so! Closing it then.
GuillaumeGomez
on 27 Sep 2018
Related issues
defuz
路
3Comments
dnsl48
路
3Comments
drewcrawford
路
3Comments
dtolnay
路
3Comments
mcarton
路
3Comments
Most helpful comment
51956 has been merged. I'm not clear if that was expected to fix this problem, because I'm still getting failures to build docs due to
#![deny(warnings)]in upstream crates as of nightly 2018-07-13: