docs(gctx): explain Value deserialization step-by-step

Author: weihanglo

src/cargo/util/context/value.rs

@@ -16,14 +16,34 @@
 //!
 //! ## How `Value<T>` deserialization works
 //!
-//! You'll want to also check out the implementation of `ValueDeserializer` in
-//! the [`de`] module. Also note that the names below are intended to be invalid
-//! Rust identifiers to avoid conflicts with other valid structures.
+//! The deserialization process works through a custom protocol:
 //!
-//! 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`].
+//! 1. When serde discovers it needs to deserialize a `Value<T>`, it calls
+//!    `Value<T>::deserialize`.
+//!
+//! 2. `Value<T>::deserialize` calls `deserializer.deserialize_struct()` with
+//!    special identifiers: a [struct name](NAME) and [field names](FIELDS).
+//!
+//! 3. When the deserializer recognizes these magic identifiers, it constructs
+//!    `ValueDeserializer` (from the [`de`] module) to provide both the value
+//!    and the definition.
+//!
+//! 4. `ValueDeserializer` provides data back to `ValueVisitor` through the
+//!    serde `MapAccess` interface, presenting the actual deserialized value
+//!    and the definition context as two fields:
+//!
+//!    * For the value field, the original deserializer performs whatever
+//!      deserialization it needs to deserialize the actual value.
+//!    * For the definition field, it is transmitted as a `(u32, String)` tuple,
+//!      which acts as a tagged union of [`Definition`] variants.
+//!
+//! 5. `ValueVisitor` constructs the complete `Value<T>` from both pieces and
+//!    returns it back through the deserializer chain to complete the original
+//!    `Value<T>::deserialize` call.
+//!
+//! **Note**: When modifying [`Definition`] variants, update both the
+//! `Definition::deserialize` implementation here and the
+//! `MapAccess::next_value_seed` implementation in `ValueDeserializer`.
 //!
 //! [`de`]: crate::util::context::de
 
@@ -48,6 +68,8 @@ pub struct Value<T> {
 
 pub type OptValue<T> = Option<Value<T>>;
 
+// The names below are intended to be invalid Rust identifiers
+// to avoid conflicts with other valid structures.
 pub(crate) const VALUE_FIELD: &str = "$__cargo_private_value";
 pub(crate) const DEFINITION_FIELD: &str = "$__cargo_private_definition";
 pub(crate) const NAME: &str = "$__cargo_private_Value";