r? @ehuss

(rust-highfive has picked a reviewer for you, use r? to override)

Thanks for the PR! The team talked about this a bit, and we had a few comments:

• What is the use case for this? I would assume that if you are packaging or otherwise collecting the build results somewhere, that you have an outer build system or script that can do the same task of copying the files.
• We were thinking this seems essentially the same as --out-dir. We were thinking that it would probably be best to avoid adding too many different options, so perhaps this should just be the same as --out-dir?
  • Related to that, unfortunately --out-dir is not really on a path to ever being stabilized. We're happy to include cargo doc with --out-dir, this is just a heads-up that it's not clear how it will move forward.

I can chime into this from my perspective.

Yes, this is exactly like --out-dir, just implemented specifically for doc. I agree that consolidating the two makes sense. I don't know that the current implementation of --out-dir allows setting it just for [doc], but if it did, it'd at least solve my use-case.

As for what that use-case is, for me at least the hope is to encode information about where other tools look for documentation directly into Cargo's configuration so that users can just run cargo doc and the documentation is automatically included in whatever those other tools may be (which suggests >1 out-dirs should be specifiable, but that's a separate point). Concretely, in my case, I have an external build system that links and exports any documentation present in a particular subdirectory of a folder named build, and I would like users using Cargo to be able to just use cargo doc, and still have their docs published to the external build system as well. out-dir would do that wonderfully.

I've tagged this as waiting-on-author now as the consensus seems to be that if we are to implement a feature such as this it would be done with --out-dir

Closing per the conversation above about not wishing to add a new flag for this.