As the ecosystem is still highly unstable at the moment (count how many
0.x.x crates out there!), the
docs.rs does not always representing the correct versions in your own crate. It is not uncommon that you find yourself in a situation that looking at the wrong document without noticing the version number. So it would be good to increase local document accessability.
However in my experience there are some issues:
rustup docincludes build-in crates, and
cargo docincludes crates referenced by project. They don’t have any integration, makes it hard to switch between.
Right now, when building documents it uses the same dependency system as building the code. But this is not right: a crate document “uses” another crate document only when it should create links to the other. For example, if a crate uses
uuidand never has it in public API,
uuidshould not need to be built when building the crate. To verify examples, of cause it should build the code referenced; but this should not be part of
cargo doc's work, it should be part of
cargo test --docinstead.
Because of the above, it takes too long to having the documents build in a typical project (for example, an
actix-webproject. In Windows for example, most of the time were spent on building
winapi, which is a too low leveled crate that most developers will not even need to think about. Yet unfortunately there does not seem to be any way to bypass this.
Because of the long build task holds the directory lock of the target folder, you are not able to build/test whilst a
cargo docis running. This lowers the development efficiency.
The local target pages performs terrible in browser. For a typical crate that have 3XX referenced crates in build, it taks 1X seconds to have the page fully loaded. Some figured out that it is because a big (6MB)
jsfile need to be loaded for indexing purpose. I think a) this should be optimised by - say - load the js only when needed; and b) the indexing functionality should be made optional. (This, turn out, not necessory of a problem of Rustdoc, because for loading local pages in Edge this is a non-problem: loading time is 1-2 seconds, not as good as docs.rs, but much better than local pages in Firefox)
Enabling building local and up-to-date documents is actually a great benifit of Rust, if the above issues being addressed,
cargo doc will be a much more powerful assistant for developers, both new and experienced users will find it helpful.