Add rustdoc for lib.rs

src/cargo/lib.rs

@@ -6,6 +6,46 @@
 // necessarily an improvement, we prefer to not use them at this time.
 #![allow(clippy::all)]
 
+//! # Cargo as a library
+//!
+//! Cargo, the Rust package manager, is also provided as a library.
+//!
+//! Two groups of developers might benefit from this documentation:
+//!
+//! 1. External tool developers who want to reuse existing building blocks from Cargo.
+//! 2. Cargo contributors who take this as a reference of Cargo's implementation details.
+//!
+//! For the first kind of developers, using Cargo as a library has drawbacks,
+//! especially Cargo as a library is unstable,
+//! and there is no clear path to stabilize at the time of writing.
+//! See [The Cargo Book: External tools][external-tools] for more on this.
+//!
+//! For the latter, the Cargo team and contributors strive for
+//! jotting down every details from their brains in each issue and PR.
+//! However, something might just disappear in the air with no reason.
+//! This documentation can be seen as their extended minds,
+//! sharing designs and hacks behind both public and private interfaces.
+//!
+//! If you are just diving into Cargo internals, [**Cargo Architecture Overview**][architecture]
+//! is the best way to get a broader context of how Cargo works under the hood.
+//! Things also worth a read are important concepts reside in source code,
+//! which Cargo developers have been crafting for a while, such as
+//!
+//! - [`cargo::core::resolver`](crate::core::resolver),
+//! - [`cargo::core::compiler::fingerprint`](core/compiler/fingerprint/index.html),
+//! - [`cargo::util::config`](crate::util::config),
+//! - [`cargo::ops::fix`](ops/fix/index.html), and
+//! - [`cargo::sources::registry`](crate::sources::registry).
+//!
+//! The Cargo team always continues improving all external and internal documentations.
+//! If you spot anything could be better, don't hesitate to discuss with the team on
+//! Zulip [`t-cargo` stream], or [submit an issue] right on GitHub.
+//!
+//! [external-tools]: https://doc.rust-lang.org/stable/cargo/reference/external-tools.html#custom-subcommands
+//! [architecture]: https://doc.crates.io/contrib/architecture
+//! [`t-cargo` stream]: https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo
+//! [submit an issue]: https://github.com/rust-lang/cargo/issues
+
 use crate::core::shell::Verbosity::Verbose;
 use crate::core::Shell;
 use anyhow::Error;