libcnb-test: Document Docker resource teardown (#743)

Fixes #374.
GUS-W-14511364.

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Improved the consistency of all user-facing libcnb.rs error message wordings. ([#722](https://github.com/heroku/libcnb.rs/pull/722))
 - The assistance error message shown when the necessary cross-compilation tools are not found now also includes the `rustup target add` step. ([#729](https://github.com/heroku/libcnb.rs/pull/729))
+- Updated the documentation for `TestRunner::build` and `TestContext::start_container` to mention when Docker resource teardown occurs. ([#743](https://github.com/heroku/libcnb.rs/pull/743))
 
 ### Fixed
 

libcnb-test/src/test_context.rs

@@ -25,7 +25,9 @@ pub struct TestContext<'a> {
 }
 
 impl<'a> TestContext<'a> {
-    /// Starts a container using the provided [`ContainerConfig`].
+    /// Starts a detached container using the provided [`ContainerConfig`].
+    ///
+    /// After the passed function has returned, the Docker container is removed.
     ///
     /// If you wish to run a shell command and don't need to customise the configuration, use
     /// the convenience function [`TestContext::run_shell_command`] instead.

libcnb-test/src/test_runner.rs

@@ -31,6 +31,8 @@ impl TestRunner {
     /// crate, packages it as a buildpack and then invokes [pack](https://buildpacks.io/docs/tools/pack/)
     /// to build a new Docker image with the buildpacks specified by the passed [`BuildConfig`].
     ///
+    /// After the passed test function has returned, the Docker image and volumes created by Pack are removed.
+    ///
     /// Since this function is supposed to only be used in integration tests, failures are not
     /// signalled via [`Result`] values. Instead, this function panics whenever an unexpected error
     /// occurred to simplify testing code.