doc: link to GlobalContext item

Author: weihanglo

src/bin/cargo/cli.rs

@@ -25,7 +25,8 @@ pub fn main(gctx: &mut GlobalContext) -> CliResult {
 
     // Update the process-level notion of cwd
     if let Some(new_cwd) = args.get_one::<std::path::PathBuf>("directory") {
-        // This is a temporary hack. This cannot access `Config`, so this is a bit messy.
+        // This is a temporary hack.
+        // This cannot access `GlobalContext`, so this is a bit messy.
         // This does not properly parse `-Z` flags that appear after the subcommand.
         // The error message is not as helpful as the standard one.
         let nightly_features_allowed = matches!(&*features::channel(), "nightly" | "dev");

src/bin/cargo/commands/install.rs

@@ -111,7 +111,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult {
     // In general, we try to avoid normalizing paths in Cargo,
     // but in these particular cases we need it to fix rust-lang/cargo#10283.
     // (Handle `SourceId::for_path` and `Workspace::new`,
-    // but not `Config::reload_rooted_at` which is always cwd)
+    // but not `GlobalContext::reload_rooted_at` which is always cwd)
     let path = path.map(|p| paths::normalize_path(&p));
 
     let version = args.get_one::<VersionReq>("version");

src/cargo/core/compiler/job_queue/job_state.rs

@@ -28,11 +28,14 @@ pub struct JobState<'a, 'gctx> {
     /// output messages are processed on the same thread as they are sent from. `output`
     /// defines where to output in this case.
     ///
-    /// Currently the `Shell` inside `Config` is wrapped in a `RefCell` and thus can't be passed
-    /// between threads. This means that it isn't possible for multiple output messages to be
-    /// interleaved. In the future, it may be wrapped in a `Mutex` instead. In this case
+    /// Currently the [`Shell`] inside [`GlobalContext`] is wrapped in a `RefCell` and thus can't
+    /// be passed between threads. This means that it isn't possible for multiple output messages
+    /// to be interleaved. In the future, it may be wrapped in a `Mutex` instead. In this case
     /// interleaving is still prevented as the lock would be held for the whole printing of an
     /// output message.
+    ///
+    /// [`Shell`]: crate::core::Shell
+    /// [`GlobalContext`]: crate::GlobalContext
     output: Option<&'a DiagDedupe<'gctx>>,
 
     /// The job id that this state is associated with, used when sending

src/cargo/sources/config.rs

@@ -120,7 +120,7 @@ impl<'gctx> SourceConfigMap<'gctx> {
         Ok(base)
     }
 
-    /// Returns the `Config` this source config map is associated with.
+    /// Returns the [`GlobalContext`] this source config map is associated with.
     pub fn gctx(&self) -> &'gctx GlobalContext {
         self.gctx
     }

src/cargo/util/cache_lock.rs

@@ -8,7 +8,7 @@
 //!
 //! There is a global [`CacheLocker`] held inside cargo's venerable
 //! [`GlobalContext`]. The `CacheLocker` manages creating and tracking the locks
-//! being held. There are methods on `Config` for managing the locks:
+//! being held. There are methods on [`GlobalContext`] for managing the locks:
 //!
 //! - [`GlobalContext::acquire_package_cache_lock`] --- Acquires a lock. May block if
 //!   another process holds a lock.
@@ -468,7 +468,7 @@ pub struct CacheLocker {
     /// The state of the locker.
     ///
     /// [`CacheLocker`] uses interior mutability because it is stuffed inside
-    /// the global `Config`, which does not allow mutation.
+    /// [`GlobalContext`], which does not allow mutation.
     state: RefCell<CacheState>,
 }
 

src/cargo/util/config/de.rs

@@ -8,7 +8,7 @@ use std::collections::HashSet;
 use std::vec;
 
 /// Serde deserializer used to convert config values to a target type using
-/// `Config::get`.
+/// [`GlobalContext::get`].
 #[derive(Clone)]
 pub(super) struct Deserializer<'gctx> {
     pub(super) gctx: &'gctx GlobalContext,

src/cargo/util/config/environment.rs

@@ -28,18 +28,20 @@ fn make_case_insensitive_and_normalized_env(
     (case_insensitive_env, normalized_env)
 }
 
-/// A snapshot of the environment variables available to [`super::GlobalContext`].
+/// A snapshot of the environment variables available to [`GlobalContext`].
 ///
-/// Currently, the [`Context`](super::GlobalContext) supports lookup of environment variables
+/// Currently, the [`GlobalContext`] supports lookup of environment variables
 /// through two different means:
 ///
-/// - [`Context::get_env`](super::GlobalContext::get_env)
-///   and [`Context::get_env_os`](super::GlobalContext::get_env_os)
+/// - [`GlobalContext::get_env`](super::GlobalContext::get_env)
+///   and [`GlobalContext::get_env_os`](super::GlobalContext::get_env_os)
 ///   for process environment variables (similar to [`std::env::var`] and [`std::env::var_os`]),
-/// - Typed Config Value API via [`Context::get`](super::GlobalContext::get).
+/// - Typed Config Value API via [`GlobalContext::get`](super::GlobalContext::get).
 ///   This is only available for `CARGO_` prefixed environment keys.
 ///
 /// This type contains the env var snapshot and helper methods for both APIs.
+///
+/// [`GlobalContext`]: super::GlobalContext
 #[derive(Debug)]
 pub struct Env {
     /// A snapshot of the process's environment variables.
@@ -68,8 +70,8 @@ impl Env {
     pub fn new() -> Self {
         // ALLOWED: This is the only permissible usage of `std::env::vars{_os}`
         // within cargo. If you do need access to individual variables without
-        // interacting with `Config` system, please use `std::env::var{_os}`
-        // and justify the validity of the usage.
+        // interacting with the config system in [`GlobalContext`], please use
+        // `std::env::var{_os}` and justify the validity of the usage.
         #[allow(clippy::disallowed_methods)]
         let env: HashMap<_, _> = std::env::vars_os().collect();
         let (case_insensitive_env, normalized_env) = make_case_insensitive_and_normalized_env(&env);
@@ -105,9 +107,10 @@ impl Env {
         self.env.keys().filter_map(|k| k.to_str())
     }
 
-    /// Get the value of environment variable `key` through the `Config` snapshot.
+    /// Get the value of environment variable `key` through the snapshot in
+    /// [`GlobalContext`](super::GlobalContext).
     ///
-    /// This can be used similarly to `std::env::var_os`.
+    /// This can be used similarly to [`std::env::var_os`].
     /// On Windows, we check for case mismatch since environment keys are case-insensitive.
     pub fn get_env_os(&self, key: impl AsRef<OsStr>) -> Option<OsString> {
         match self.env.get(key.as_ref()) {
@@ -152,7 +155,7 @@ impl Env {
     /// Get the value of environment variable `key` as a `&str`.
     /// Returns `None` if `key` is not in `self.env` or if the value is not valid UTF-8.
     ///
-    /// This is intended for use in private methods of `Config`,
+    /// This is intended for use in private methods of [`GlobalContext`](super::GlobalContext),
     /// and does not check for env key case mismatch.
     ///
     /// This is case-sensitive on Windows (even though environment keys on Windows are usually
@@ -172,7 +175,7 @@ impl Env {
 
     /// Check if the environment contains `key`.
     ///
-    /// This is intended for use in private methods of `Config`,
+    /// This is intended for use in private methods of [`GlobalContext`](super::GlobalContext),
     /// and does not check for env key case mismatch.
     /// See the docstring of [`Env::get_str`] for more context.
     pub(super) fn contains_key(&self, key: impl AsRef<OsStr>) -> bool {

src/cargo/util/config/mod.rs

@@ -1,12 +1,12 @@
 //! Cargo's config system.
 //!
-//! The `Config` object contains general information about the environment,
+//! The [`GlobalContext`] object contains general information about the environment,
 //! and provides access to Cargo's configuration files.
 //!
 //! ## Config value API
 //!
 //! The primary API for fetching user-defined config values is the
-//! `Config::get` method. It uses `serde` to translate config values to a
+//! [`GlobalContext::get`] method. It uses `serde` to translate config values to a
 //! target type.
 //!
 //! There are a variety of helper types for deserializing some common formats:
@@ -329,7 +329,7 @@ impl GlobalContext {
         }
     }
 
-    /// Creates a new Config instance, with all default settings.
+    /// Creates a new instance, with all default settings.
     ///
     /// This does only minimal initialization. In particular, it does not load
     /// any config files from disk. Those will be loaded lazily as-needed.
@@ -811,16 +811,18 @@ impl GlobalContext {
         }
     }
 
-    /// Get the value of environment variable `key` through the `Config` snapshot.
+    /// Get the value of environment variable `key` through the snapshot in
+    /// [`GlobalContext`](super::GlobalContext).
     ///
-    /// This can be used similarly to `std::env::var`.
+    /// This can be used similarly to [`std::env::var`].
     pub fn get_env(&self, key: impl AsRef<OsStr>) -> CargoResult<String> {
         self.env.get_env(key)
     }
 
-    /// Get the value of environment variable `key` through the `Config` snapshot.
+    /// Get the value of environment variable `key` through the snapshot in
+    /// [`GlobalContext`](super::GlobalContext).
     ///
-    /// This can be used similarly to `std::env::var_os`.
+    /// This can be used similarly to [`std::env::var_os`].
     pub fn get_env_os(&self, key: impl AsRef<OsStr>) -> Option<OsString> {
         self.env.get_env_os(key)
     }
@@ -1001,7 +1003,7 @@ impl GlobalContext {
             .map_err(|e| anyhow!("invalid configuration for key `{}`\n{}", key, e))
     }
 
-    /// Update the Config instance based on settings typically passed in on
+    /// Update the instance based on settings typically passed in on
     /// the command-line.
     ///
     /// This may also load the config from disk if it hasn't already been
@@ -1646,7 +1648,7 @@ impl GlobalContext {
     ///
     /// The credentials are loaded into a separate field to enable them
     /// to be lazy-loaded after the main configuration has been loaded,
-    /// without requiring `mut` access to the `Config`.
+    /// without requiring `mut` access to the [`GlobalContext`].
     ///
     /// If the credentials are already loaded, this function does nothing.
     pub fn load_credentials(&self) -> CargoResult<()> {

src/doc/contrib/src/implementation/console.md

@@ -1,8 +1,8 @@
 # Console Output
 
 All of Cargo's output should go through the [`Shell`] struct. You can normally
-obtain the `Shell` instance from the [`Config`] struct. Do **not** use the std
-`println!` macros.
+obtain the `Shell` instance from the [`GlobalContext`] struct. Do **not** use
+the std `println!` macros.
 
 Most of Cargo's output goes to stderr. When running in JSON mode, the output
 goes to stdout.
@@ -17,7 +17,7 @@ if they are unable to be displayed. This is generally automatically handled in
 the [`JobQueue`] as it processes each message.
 
 [`Shell`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/shell.rs
-[`Config`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/config/mod.rs
+[`GlobalContext`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/config/mod.rs
 [`drop_print`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1820-L1848
 [`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue/mod.rs
 

tests/testsuite/config.rs

@@ -80,22 +80,22 @@ impl GlobalContextBuilder {
     /// Sets the test root directory.
     ///
     /// This generally should not be necessary. It is only useful if you want
-    /// to create a `Config` from within a thread. Since Cargo's testsuite
-    /// uses thread-local storage, this can be used to avoid accessing that
-    /// thread-local storage.
+    /// to create a [`GlobalContext`] from within a thread. Since Cargo's
+    /// testsuite uses thread-local storage, this can be used to avoid accessing
+    /// that thread-local storage.
     ///
     /// Default is [`paths::root`].
     pub fn root(&mut self, path: impl Into<PathBuf>) -> &mut Self {
         self.root = Some(path.into());
         self
     }
 
-    /// Creates the `Config`.
+    /// Creates the [`GlobalContext`].
     pub fn build(&self) -> GlobalContext {
         self.build_err().unwrap()
     }
 
-    /// Creates the `Config`, returning a Result.
+    /// Creates the [`GlobalContext`], returning a Result.
     pub fn build_err(&self) -> CargoResult<GlobalContext> {
         let root = self.root.clone().unwrap_or_else(|| paths::root());
         let output = Box::new(fs::File::create(root.join("shell.out")).unwrap());