More docs

commons/src/layer/cache_buddy.rs

@@ -40,6 +40,8 @@
 //! build output. If the cache is cleared for any reason, then a user readable message is returned. This message should
 //! be printed to the buildpack user so they can understand what caused the cache to clear.
 //!
+#![doc = include_str!("./fixtures/cache_buddy_example.md")]
+
 use crate::display::SentenceList;
 use cache_diff::CacheDiff;
 use libcnb::build::BuildContext;
@@ -64,6 +66,7 @@ use std::fmt::Debug;
 ///   When a `CacheDiff::diff` is empty, the layer is kept and the old data is returned. Otherwise,
 ///   the layer is deleted and the changes are returned.
 ///
+#[doc = include_str!("./fixtures/cache_buddy_example.md")]
 #[derive(Default, Debug, Clone, Eq, PartialEq)]
 pub struct CacheBuddy {
     pub build: Option<bool>,
@@ -212,6 +215,12 @@ impl<M> AsRef<str> for Meta<M> {
 }
 
 /// Takes in a directory and returns a minimal build context for use in testing caching behavior
+///
+/// Public for use in doc tests, but the interface is not stable.
+///
+/// # Panics
+///
+/// - If a context cannot be created
 #[cfg(test)]
 fn temp_build_context<B: libcnb::Buildpack>(
     from_dir: impl AsRef<std::path::Path>,
@@ -284,7 +293,6 @@ mod tests {
     migrate_toml_chain! {TestMetadata}
 
     struct FakeBuildpack;
-
     impl libcnb::Buildpack for FakeBuildpack {
         type Platform = GenericPlatform;
         type Metadata = GenericMetadata;

commons/src/layer/fixtures/cache_buddy_example.md

@@ -0,0 +1,83 @@
+# Example
+
+```
+use commons::layer::cache_buddy::CacheBuddy;
+use commons::layer::cache_buddy::Meta;
+use cache_diff::CacheDiff;
+use magic_migrate::TryMigrate;
+use serde::Deserializer;
+
+use libcnb::layer::{LayerState, EmptyLayerCause};
+use libcnb::data::layer_name;
+
+# #[derive(Debug, serde::Serialize, serde::Deserialize, Clone, cache_diff::CacheDiff)]
+# #[serde(deny_unknown_fields)]
+# struct TestMetadata {
+#     value: String,
+# }
+# use magic_migrate::Migrate;
+# magic_migrate::migrate_toml_chain!(TestMetadata);
+#
+# struct FakeBuildpack;
+#
+# impl libcnb::Buildpack for FakeBuildpack {
+#     type Platform = libcnb::generic::GenericPlatform;
+#     type Metadata = libcnb::generic::GenericMetadata;
+#     type Error = std::convert::Infallible;
+#
+#     fn detect(
+#         &self,
+#         _context: libcnb::detect::DetectContext<Self>,
+#     ) -> libcnb::Result<libcnb::detect::DetectResult, Self::Error> {
+#         todo!()
+#     }
+#
+#     fn build(
+#         &self,
+#         _context: libcnb::build::BuildContext<Self>,
+#     ) -> libcnb::Result<libcnb::build::BuildResult, Self::Error> {
+#         todo!()
+#     }
+# }
+# fn install_ruby(path: &std::path::Path) {
+#   todo!();
+# }
+#
+# pub(crate) fn call(
+#     context: &libcnb::build::BuildContext<FakeBuildpack>,
+# ) -> libcnb::Result<(), <FakeBuildpack as libcnb::Buildpack>::Error> {
+# let metadata_owned = TestMetadata { value: "Hello".to_string() };
+# let metadata = &metadata_owned;
+let layer_ref = CacheBuddy::new().layer(layer_name!("ruby"), context, metadata)?;
+match &layer_ref.state {
+    // CacheDiff reported no difference, cache was kept
+    LayerState::Restored { cause } => {
+        println!("  - {cause}"); // States that the cache is being used
+        match cause {
+            Meta::Data(old) => {
+                // Inspect or use the old metadata from cache here if you like!
+                assert!(metadata.diff(old).is_empty());
+            },
+            Meta::Message(_) => unreachable!("Will only ever contain metadata when the cache is retained")
+        }
+    }
+    LayerState::Empty { cause } => {
+        match cause {
+            // Nothing in old cache
+            EmptyLayerCause::NewlyCreated => {}
+            // Problem restoring old cache (`TryMigrate` could not migrate the old metadata)
+            EmptyLayerCause::InvalidMetadataAction { cause }
+            // Difference with old cache
+            | EmptyLayerCause::RestoredLayerAction { cause } => {
+                // Report why the cache was cleared
+                println!("  - {cause}");
+            }
+        }
+        println!("  - Installing");
+        install_ruby(&layer_ref.path());
+        println!("  - Done");
+    }
+}
+# Ok(())
+# }
+```