rustdoc should be able to build documentation from compiled crates

[brson]

rustdocs are built from attributes which are (should be) stored in the crate metadata. rustdoc should be able to construct the crate documentation from the crate metadata with nearly the same fidelity as from the original source.

Update(2024, fmease): In today's terms, this essentially asks for the option¹ to build docs based on rustc_middle::ty instead of the HIR in the all cases, not just for inlined cross-crate re-exports and synthetic impls.

Footnotes

1. Some t-rustdoc members (incl. myself, @fmease) are even inclined to drop "HIR cleaning" entirely once the important A-cross-crate-reexports Area: Documentation that has been re-exported from a different crate issues have been addressed (which is non-trivial I have to add). In the long term, that move would greatly improve the correctness of rustdoc and make it easier to develop certain features. Namely anything that depends on more complex "type-based reasoning" (for which rustc_middle::ty is a lot better suited compared to the HIR). ↩

[msullivan]

Part of #5413, I suppose.

[emberian]

#8125

This is not yet implemented by rustdoc_ng.

[catamorphism]

Low, not 1.0

[alexcrichton]

Note that all of the infrastructure is in place for doing this, there's just a few more wires to put in place.

[flaper87]

Triage bump: Still an issue. Priorities and tags seem correct to me. (cc @steveklabnik to make sure he's notified when things change here)

[steveklabnik]

Triage: no changes here.

[steveklabnik]

Triage: no changes, but this is certainly desired, especially with cargo check, that didn't exist the last time this was commented on.

[jyn514]

Triage: no changes, but this is certainly desired, especially with cargo check, that didn't exist the last time this was commented on.

I think cargo check is a little misleading - rustdoc already reads cargo check metadata for dependencies, which you can see from experimenting a little with cargo:

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

and documenting also shares the same metadata cache as checking:

$ cargo check
    Checking hello-world v0.1.0 (/home/joshua/src/rust/test-rustdoc/hello-world)
    Finished dev [unoptimized + debuginfo] target(s) in 0.49s
$ cargo doc
 Documenting hello-world v0.1.0 (/home/joshua/src/rust/test-rustdoc/hello-world)
    Finished dev [unoptimized + debuginfo] target(s) in 0.67s
$ rm -r target
$ cargo doc
 Documenting hello-world v0.1.0 (/home/joshua/src/rust/test-rustdoc/hello-world)
    Finished dev [unoptimized + debuginfo] target(s) in 1.36s
$ cargo check
    Checking hello-world v0.1.0 (/home/joshua/src/rust/test-rustdoc/hello-world)
    Finished dev [unoptimized + debuginfo] target(s) in 0.11s

I guess my question is what this would be useful for? It seems weird to want to document a crate without having the source available. Rustdoc also has a bunch of subtle bugs about how metadata handling is different from HIR handling, which would suddenly start applying to the main crate instead of only on re-exports: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+crate+label%3AA-cross-crate-reexports

[bjorn3]

and documenting also shares the same metadata cache as checking:

But it does still require compiling every crate twice. Once for crate metadata to be used when documenting crates that depend on the current crate and once to actually generate documentation for the current crate.

It seems weird to want to document a crate without having the source available.

Could be useful for closed-source crates. And as a side-effect clearly show just how much information is leaked in the crate metadata, which could help dissuade people from releasing crates as closed source rlibs that can then only be used by a single rustc version. And instead push them towards either making it source available or releasing it as a cdylib with a stable abi such that it can be used with any rustc version.

[jyn514]

as a side-effect clearly show just how much information is leaked in the crate metadata, which could help dissuade people from releasing crates as closed source rlibs that can then only be used by a single rustc version

Having a tool for this seems useful, but I don't know that rustdoc needs to be that tool. Rustdoc has already had several major expansions of scope.

Given the complexity of the implementation, the fact it will likely change various parts of the rendering (https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+crate+label%3AA-cross-crate-reexports), and the unclear use cases, I think this would benefit from an RFC that explains why this functionality belongs in rustdoc.