Issues of cargo-doc

[earthengine]

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:

1. The rustup doc includes build-in crates, and cargo doc includes crates referenced by project. They don’t have any integration, makes it hard to switch between.

2. 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 uuid and never has it in public API, uuid should 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 --doc instead.

3. Because of the above, it takes too long to having the documents build in a typical project (for example, an actix-web project. 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.

4. Because of the long build task holds the directory lock of the target folder, you are not able to build/test whilst a cargo doc is running. This lowers the development efficiency.

5. 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) js file 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.

[DanielKeep]

As the ecosystem is still highly unstable at the moment (count how many 0.x.x crates out there!)

This horse should’ve been buried long ago, but it seems it still needs beating:

Version numbers do not denote stability. A 0.* crate can be stable. A 1.* crate can be unstable. A crate’s first version could be 0.0.1, 0.1.0, 1.0.0, or 3.9.67. The only notional meaning version numbers have is backward compatibility.

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.

It has to be able to build the code in order to understand it so it can document it. It can’t do that if it doesn’t understand the dependencies.

---

Local cargo doc could absolutely be improved, but it’s somewhat limited by needing to open the result in a browser. A more effective short-term solution might be to contrive some way to open docs.rs with the relevant parts of Cargo.lock, so that it shows the documentation for just the crates you’re using.

Maybe do a POST of a trimmed-down Cargo.lock to docs.rs, which returns a URL that cargo then opens with the browser.

[earthengine]

Version numbers do not denote stability.

Yes I know that. However, the unstablity is in fact the case for many popular crates like actix-web, hyper, tokio or things like that, because of the busy development circle of async/await and future features. This sort of things, are not stable even today in the core language, so the ecosystem have no way to stablise itself.

It has to be able to build the code in order to understand it so it can document it. It can’t do that if it doesn’t understand the dependencies.

This is true; however, Rust documents are able to hide informations that is not in the public interface. It does not have to look at the example codes, don’t have to look at function code etc.

Furthermore, for example even when building ws2_32-sys requires winapi, it need not build winapi's document, if it does not re-export the types/functions in winapi. All it have to do is build the code of winapi , which is much faster (in <10 minutes) than build the document (in hours).

[DanielKeep]

All it have to do is build the code of winapi , which is much faster (in <10 minutes) than build the document (in hours).

Which is what --no-deps does. That plus -p PKG documents just the packages you want.

(Yes, more to type, yes, it would be nice to be able to write this down as a default somewhere.)

[earthengine]

Which is what --no-deps does.

I didn’t know that; but I am afraid this is not what I want - hyper re-exports http types, I would expect when I hit the link on Request it lead me to the right http documentation page, not a 404 or a piece of dead text. I guess --no-deps will not be clever enough to do this for me?

[DanielKeep]

It’s no dependencies. You should be able to specify multiple packages, though: -p hyper -p http, but I don’t recall ever specifically trying that.

[earthengine]

It turns out the bad performance have to do with Firefox - it is much faster in Edge. I would raise an issue on Firefox.

[kornel]

Version numbers do not denote stability.

They should though. Maybe we need to nugde crate authors harder to start using 1.x.

Currently 1.0.0 is treated as a very serious goal, almost as if this was going to be the last and final version of the crate.