Add docs, change generic letter

buildpacks/ruby/src/layers/shared.rs

@@ -36,18 +36,38 @@ where
     Ok(layer_ref)
 }
 
-pub(crate) enum CacheState<T> {
+/// Either contains metadata or a message describing the state
+///
+/// Why: The `CachedLayerDefinition` allows returning information about the cache state
+/// from either `invalid_metadata_action` or `restored_layer_action` functions.
+///
+/// Because the function returns only a single type, that type must be the same for
+/// all possible cache conditions (cleared or retained). Therefore, the type must be
+/// able to represent information about the cache state when it's cleared or not.
+///
+/// This struct implements `Display` and `AsRef<str>` so if the end user only
+/// wants to advertise the cache state, they can do so by passing the whole struct
+/// to `format!` or `println!` without any further maniuplation. If they need
+/// to inspect the previous metadata they can match on the enum and extract
+/// what they need.
+///
+/// - Will only ever contain metadata when the cache is retained.
+/// - Will contain a message when the cache is cleared, describing why it was cleared.
+///   It is also allowable to return a message when the cache is retained, and the
+///   message describes the state of the cache. (i.e. because a message is returned
+///   does not guarantee the cache was cleared).
+pub(crate) enum CacheState<M> {
     Message(String),
-    Data(T),
+    Data(M),
 }
 
-impl<T> Display for CacheState<T> {
+impl<M> Display for CacheState<M> {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(f, "{}", self.as_ref())
     }
 }
 
-impl<T> AsRef<str> for CacheState<T> {
+impl<M> AsRef<str> for CacheState<M> {
     fn as_ref(&self) -> &str {
         match self {
             CacheState::Message(s) => s.as_str(),