rustdoc exits with an error on crate-level `#![doc(hidden)]`

jotare commented 1 year ago

Problem

Hi, I found a possible bug (or at least, bad error message) while generating documentation for a library with #![doc(hidden)]. The use case is a library with private documentation published to crates.io. The docs page is generated and failing. In the docs page you see all broken but no documentation is intended.

(It's a third party crate so I don't have decision on having no documentation)

The error thrown by cargo doc is somewhat obscure, as hiding docs is intentional:

error: couldn't generate documentation: No such file or directory (os error 2)
  |
  = note: failed to create or modify "/home/.../hidden-docs-bug/target/doc/hidden_docs_bug/all.html"

error: could not document `hidden-docs-bug`

Caused by:
  process didn't exit successfully: `rustdoc --edition=2021 --crate-type lib --crate-name hidden_docs_bug src/lib.rs -o /home/.../hidden-docs-bug/target/doc --error-format=json --json=diagnostic-rendered-ansi,artifacts,future-incompat --diagnostic-width=105 -C metadata=5b17bc2b2d87366d -L dependency=/home/.../hidden-docs-bug/target/debug/deps --crate-version 0.1.0` (exit status: 1)

(Full paths have been trimmed)

I'd expect docs to be generated and either an empty docs page or with a simple message indicating this crate has no/hidden docs.

Steps

Create a new cargo project:
```
cargo init hidden-docs-bug
```
Open src/lib.rs and add a #![doc(hidden)] in the beginning of the file.
Generate docs using cargo doc.

Possible Solution(s)

I'd expect something like either generating an empty docs page or with a simple message indicating docs are hidden for this crate.

Notes

No response

Version

cargo 1.68.0 (115f34552 2023-02-26)
release: 1.68.0
commit-hash: 115f34552518a2f9b96d740192addbac1271e7e6
commit-date: 2023-02-26
host: x86_64-unknown-linux-gnu
libgit2: 1.5.0 (sys:0.16.0 vendored)
libcurl: 7.86.0-DEV (sys:0.4.59+curl-7.86.0 vendored ssl:OpenSSL/1.1.1q)
os: Ubuntu 22.04 (jammy) [64-bit]

ehuss commented 1 year ago

Thanks for the report! This appears to be an issue with rustdoc, and its issue tracker lives here.

jyn514 commented 1 year ago

Putting doc(hidden) on the entire crate is ... a very strange decision. I am not sure what the semantics of that should be.

The use case is a library with private documentation published to crates.io.

What does this mean? docs.rs intentionally does not have an opt-out mechanism: https://github.com/rust-lang/docs.rs/issues/125

jotare commented 1 year ago

Thanks for the quick reply!

Putting doc(hidden) on the entire crate is ... a very strange decision. I am not sure what the semantics of that should be.

Yes, I also think so. In my opinion, an empty docs page (or something similar) or a better error, both might have sense

What does this mean? docs.rs intentionally does not have an opt-out mechanism: rust-lang/docs.rs#125

I first opened an issue to this crate, so I link to it so you can have more context: https://github.com/taiki-e/cargo-llvm-cov/issues/248

GuillaumeGomez commented 1 year ago

I personally think it's an acceptable behaviour. It'll just create an empty documentation and that's it. Seems like a weird use case indeed though.

I opened https://github.com/rust-lang/rust/pull/109726 which fixes the rustdoc crash in the meantime (which therefore generates empty documentation).

rust-lang / rust