rust-lang
RFC: Rustdoc configuration via Cargo (includes feature descriptions)
RFC for rustdoc-cargo-configuration
This RFC describes a way for rustdoc to get information from Cargo.toml. Its main use case is the Cargo feature descriptions RFC https://github.com/rust-lang/rfcs/pull/3416.
The implementation goal of this RFC is only to get rustdoc working. However, it describes a flexible configuration that could be implemented for other tools (rustfmt, clippy, or any of the cargo-xyz tools) and can be used by build systems other than Cargo (e.g. Make or some WASM extensions of npm)
Related:
- https://github.com/rust-lang/rfcs/pull/3389
- https://github.com/rust-lang/rust/issues/44690
I'm going to mark this RFC as a draft again, just since I'd like to focus on https://github.com/rust-lang/rfcs/pull/3416 first, and also have some coordination to do with the tools teams. I do intend to keep the overall idea the same, so feedback is still very much welcome.
As maintainer of cargo-semver-checks, having data on crate features (including default features, which other features they require, and what features each requires in dependencies) would be very helpful. I believe all those data points may be the cause of accidental SemVer breakage, and it would both massively simplify my life and offer better ergonomics for cargo-semver-checks users if that data were part of rustdoc JSON.
Happy to go into details if anyone is curious.
As maintainer of cargo-semver-checks, having data on crate features (including default features, which other features they require, and what features each requires in dependencies) would be very helpful. I believe all those data points may be the cause of accidental SemVer breakage, and it would both massively simplify my life and offer better ergonomics for cargo-semver-checks users if that data were part of rustdoc JSON.
If rustdoc is like rustc, then it will have little to no cargo knowledge and extending it with this knowledge in a non-abstract way would be violating these separation of concerns.
I also see this as a shortcut. It might help you in the short term to have rustdoc expose it but there is other semver-relevant content in manifests that will need checking, like public-private dependencies which are just a couple bugs in rustc away from being stabilized.
If rustdoc is like rustc, then it will have little to no cargo knowledge and extending it with this knowledge in a non-abstract way would be violating these separation of concerns.
I also see this as a shortcut.
I don't dispute this. But if rustdoc is already including info on features and descriptions, then all your concerns still apply regardless of cargo-semver-checks, no?
If there's already going to be an officially-supported of getting the information we need into rustdoc, I don't want to unnecessarily maintain another one. It's better for the entire community if we don't needlessly duplicate work.
Even if we eventually need more information than it makes sense for rustdoc to include, and cargo-semver-checks ends up parsing manifests anyway, getting more functionality available sooner and at lesser development and maintenance cost is worth it in itself IMHO.
I don't dispute this. But if rustdoc is already including info on features and descriptions, then all your concerns still apply regardless of cargo-semver-checks, no?
If there's already going to be an officially-supported of getting the information we need into rustdoc, I don't want to unnecessarily maintain another one.
This depends on what rustdoc / cargo find appropriate to pass to rustdoc. It could be as simple as cfgs and documentation for cfgs and their values. That would lose high level information you need like requires
It's better for the entire community if we don't needlessly duplicate work.
Even if we eventually need more information than it makes sense for rustdoc to include, and cargo-semver-checks ends up parsing manifests anyway, getting more functionality available sooner and at lesser development and maintenance cost is worth it in itself IMHO.
This feels like an overly broad generalization. Just because something exists and is of interest for cargo-semver-checks it, doesn't mean it is needed for rendering documentation, will be presented / modeled in a way that is relevant for cargo-semver-checks, or be implemented in a timely manner as any cargo information requires new CLI contracts between rustdoc and cargo.