Document compiler/ with -Aprivate-intra-doc-links #83885
Conversation
Since compiler/ always passes --document-private-items, it's ok to link to items that are private.
|
(rust-highfive has picked a reviewer for you, use r? to override) |
|
Note that this came to mind because I fixed an existing bug in the lint: #83849 (comment). So we are missing out on dogfooding a bit. But I don't want people to think they should remove links because of the lint. |
| @@ -549,6 +549,8 @@ impl Step for Rustc { | |||
| // Build cargo command. | |||
| let mut cargo = builder.cargo(compiler, Mode::Rustc, SourceType::InTree, target, "doc"); | |||
| cargo.rustdocflag("--document-private-items"); | |||
| // Since we always pass --document-private-items, there's no need to warn about linking to private items. | |||
| cargo.rustdocflag("-Arustdoc::private-intra-doc-links"); | |||
There was a problem hiding this comment.
Hm, should this perhaps go in builder::cargo along with the other lint configs, gated on Mode::Rustc?
There was a problem hiding this comment.
I think it should go next to --document-private-items, wherever that is, so people can see they're related. Happy to move --document-private-items to builder::cargo if you think it's useful.
There was a problem hiding this comment.
Is there a reason rustdoc isn't changing the default lint level when that flag is passed?
There was a problem hiding this comment.
It's actually part of the error message:
error: public documentation for `ModuleData` links to private item `ModuleData::kind`
|
|
496 | /// You can use [`ModuleData::kind`] to determine the kind of module this is.
|
|
= note: `-D rustdoc::private-intra-doc-links` implied by `-D warnings`
= note: this link resolves only because you passed `--document-private-items`, but will break without
I do think it should be something intentional, I expect at least some people only document locally with --document-private-items and I think they should still see the warning unless they opt out. Otherwise the links will be broken on docs.rs.
There was a problem hiding this comment.
Hm. I'm not sure I buy that argument; users likely run in CI without document-private-items and so will see the error there (as warnings are likely to be denied). But regardless, that seems like an orthogonal discussion. I'm happy to merge this.
|
@bors r+ rollup |
|
📌 Commit 0a351ab has been approved by |
…crum Document compiler/ with -Aprivate-intra-doc-links Since compiler/ always passes --document-private-items, it's ok to link to items that are private.
…crum Document compiler/ with -Aprivate-intra-doc-links Since compiler/ always passes --document-private-items, it's ok to link to items that are private.
Rollup of 8 pull requests Successful merges: - rust-lang#83370 (Add `x.py setup tools` which enables `download-rustc` by default) - rust-lang#83489 (Properly suggest deref in else block) - rust-lang#83734 (Catch a bad placeholder type error for statics in `extern`s) - rust-lang#83814 (expand: Do not ICE when a legacy AST-based macro attribute produces and empty expression) - rust-lang#83835 (rustdoc: sort search index items for compression) - rust-lang#83849 (rustdoc: Cleanup handling of associated items for intra-doc links) - rust-lang#83881 (:arrow_up: rust-analyzer) - rust-lang#83885 (Document compiler/ with -Aprivate-intra-doc-links) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup
Since compiler/ always passes --document-private-items, it's ok to link to items that are private.