cargo doc fails for the h2 crate (v0.1.9) on nightly 2018-06-05

[jimmycuadra]

$ 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)

[pietroalbini]

This is a regression from stable to nightly. cc @rust-lang/rustdoc

[GuillaumeGomez]

No it's not, it's a nightly version using a nightly feature (intra-link to exact).

[QuietMisdreavus]

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 #50561. Everything else is just warnings that lead up to that point.`

[QuietMisdreavus]

Good news: The compile error shown in the issue description was fixed in #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 #51684.

[cramertj]

@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?

[GuillaumeGomez]

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.

[cramertj]

@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.

[QuietMisdreavus]

@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.

[GuillaumeGomez]

@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.

[rtsuk]

@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.

[QuietMisdreavus]

I wonder, now that #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...

[GuillaumeGomez]

Once #51956 is merged, your problem should be solved.

[dgrnbrg]

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.

[jimmycuadra]

#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`.

[rtsuk]

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.

[kzys]

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                  
%

[GuillaumeGomez]

Seems so! Closing it then.