docs(gctx): intra doc links and grammartical fixes for Value

Author: weihanglo

src/cargo/util/context/value.rs

@@ -1,5 +1,6 @@
-//! Deserialization of a `Value<T>` type which tracks where it was deserialized
-//! from.
+//! Deserialization of a [`Value<T>`] type which tracks where it was deserialized from.
+//!
+//! ## Rationale for `Value<T>`
 //!
 //! Often Cargo wants to report semantic error information or other sorts of
 //! error information about configuration keys but it also may wish to indicate
@@ -8,23 +9,30 @@
 //! from configuration, but also record where it was deserialized from when it
 //! was read.
 //!
+//! ## How `Value<T>` deserialization works
+//!
 //! Deserializing `Value<T>` is pretty special, and serde doesn't have built-in
 //! support for this operation. To implement this we extend serde's "data model"
 //! a bit. We configure deserialization of `Value<T>` to basically only work with
 //! our one deserializer using configuration.
 //!
 //! We define that `Value<T>` deserialization asks the deserializer for a very
-//! special struct name and struct field names. In doing so the deserializer will
-//! recognize this and synthesize a magical value for the `definition` field when
-//! we deserialize it. This protocol is how we're able to have a channel of
-//! information flowing from the configuration deserializer into the
-//! deserialization implementation here.
+//! special [struct name](NAME) and [struct field names](FIELDS). In doing so,
+//! the deserializer will recognize this and synthesize a magical value for the
+//! `definition` field when we deserialize it. This protocol is how we're able
+//! to have a channel of information flowing from the configuration deserializer
+//! into the deserialization implementation here.
 //!
 //! You'll want to also check out the implementation of `ValueDeserializer` in
-//! `de.rs`. Also note that the names below are intended to be invalid Rust
-//! identifiers to avoid how they might conflict with other valid structures.
-//! Finally the `definition` field is transmitted as a tuple of i32/string, which
-//! is effectively a tagged union of `Definition` itself.
+//! the [`de`] module. Also note that the names below are intended to be invalid
+//! Rust identifiers to avoid conflicts with other valid structures.
+//!
+//! Finally the `definition` field is transmitted as a tuple of i32/string,
+//! which is effectively a tagged union of [`Definition`] itself. You should
+//! update both places here and in the impl of [`serde::de::MapAccess`] for
+//! `ValueDeserializer` when adding or modifying enum variants of [`Definition`].
+//!
+//! [`de`]: crate::util::context::de
 
 use crate::util::context::GlobalContext;
 use serde::de;