documentation: add docs to componnet-related modules

Signed-off-by: Jiaxiao Zhou <duibao55328@gmail.com>

Author: Mossaka

crates/wassette/src/component_storage.rs

@@ -1,3 +1,9 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+//! Filesystem helpers that manage component artifacts, metadata, and cache
+//! layout for the lifecycle manager.
+
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
@@ -158,7 +164,11 @@ impl ComponentStorage {
         Ok(())
     }
 
-    /// Create a validation stamp for a file.
+    /// Create a validation stamp for a component artifact to track stale data on disk.
+    ///
+    /// When `include_hash` is `true` the SHA-256 hash of the file is
+    /// recorded in addition to size and modification time so changes can be
+    /// detected even when timestamps are unreliable.
     pub async fn create_validation_stamp(
         path: &Path,
         include_hash: bool,

crates/wassette/src/config.rs

@@ -1,3 +1,9 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+//! Builder and configuration helpers for constructing
+//! [`LifecycleManager`](crate::LifecycleManager).
+
 use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::time::Duration;
@@ -83,6 +89,8 @@ pub struct LifecycleBuilder {
 }
 
 impl LifecycleBuilder {
+    /// Create a builder with sensible defaults for the provided plugin
+    /// directory.
     pub(crate) fn new(plugin_dir: PathBuf) -> Self {
         Self {
             plugin_dir,
@@ -163,7 +171,12 @@ impl LifecycleBuilder {
         })
     }
 
-    /// Construct a [`LifecycleManager`], optionally performing eager loading.
+    /// Construct a [`LifecycleManager`] using the current builder settings.
+    ///
+    /// If eager loading is enabled the plugin directory is scanned
+    /// immediately; otherwise the caller can defer loading until a later
+    /// [`LifecycleManager::load_all_components`](crate::LifecycleManager::load_all_components)
+    /// invocation.
     pub async fn build(self) -> Result<LifecycleManager> {
         let config = self.build_config()?;
         let eager = config.eager_load();
@@ -175,6 +188,7 @@ impl LifecycleBuilder {
     }
 }
 
+/// Create the default HTTP client used when none is supplied.
 fn default_http_client() -> Result<reqwest::Client> {
     let http_timeout = std::env::var("HTTP_TIMEOUT_SECS")
         .ok()
@@ -187,6 +201,7 @@ fn default_http_client() -> Result<reqwest::Client> {
         .context("Failed to create default HTTP client")
 }
 
+/// Create the default OCI client used when none is supplied.
 fn default_oci_client() -> Result<oci_client::Client> {
     let oci_timeout = std::env::var("OCI_TIMEOUT_SECS")
         .ok()
@@ -213,6 +228,8 @@ impl LifecycleConfig {
     }
 }
 
+/// Internal helper that exposes the decomposed configuration values to the
+/// lifecycle manager for initialization.
 pub(crate) struct LifecycleConfigParts {
     pub plugin_dir: PathBuf,
     pub secrets_dir: PathBuf,

crates/wassette/src/lib.rs

@@ -300,7 +300,8 @@ pub struct ComponentInstance {
 }
 
 impl LifecycleManager {
-    /// Begin constructing a lifecycle manager with a fluent builder.
+    /// Begin constructing a lifecycle manager with a fluent builder that
+    /// validates configuration and applies sensible defaults.
     pub fn builder(plugin_dir: impl Into<PathBuf>) -> LifecycleBuilder {
         LifecycleBuilder::new(plugin_dir.into())
     }
@@ -508,7 +509,8 @@ impl LifecycleManager {
     /// Loads a new component from the given URI. This URI can be a file path, an OCI reference, or a URL.
     ///
     /// If a component with the given id already exists, it will be updated with the new component.
-    /// Returns the new ID and whether or not this component was replaced.
+    /// Returns rich [`ComponentLoadOutcome`] information describing the loaded
+    /// component and whether it replaced an existing instance.
     #[instrument(skip(self))]
     pub async fn load_component(&self, uri: &str) -> Result<ComponentLoadOutcome> {
         debug!(uri, "Loading component");

crates/wassette/src/policy_internal.rs

@@ -146,6 +146,8 @@ impl PolicyManager {
         self.build_default_template(component_id).await
     }
 
+    /// Construct a default WASI template enriched with configured environment
+    /// variables and any stored secrets for the component.
     async fn build_default_template(&self, component_id: &str) -> Arc<WasiStateTemplate> {
         let mut config_vars = self.environment_vars.as_ref().clone();
 
@@ -277,6 +279,8 @@ impl PolicyManager {
         Ok(())
     }
 
+    /// Rehydrate policy templates from a co-located policy file on disk, if
+    /// one exists for the component.
     pub(crate) async fn restore_from_disk(&self, component_id: &str) -> Result<()> {
         let policy_path = self.policy_path(component_id);
         if !policy_path.exists() {

crates/wassette/src/runtime_context.rs

@@ -1,3 +1,9 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+//! Support utilities for sharing Wasmtime engine and linker state across lifecycle
+//! manager instances.
+
 use std::sync::Arc;
 
 use anyhow::Result;
@@ -42,17 +48,18 @@ impl RuntimeContext {
         Arc::clone(&self.engine)
     }
 
-    /// Lightweight reference to the engine.
+    /// Borrow the underlying engine reference.
     pub fn engine(&self) -> &Engine {
         self.engine.as_ref()
     }
 
-    /// Accessor for the linker handle.
+    /// Accessor for the linker handle as a shareable pointer.
     pub fn linker_handle(&self) -> Arc<Linker<WassetteWasiState<WasiState>>> {
         Arc::clone(&self.linker)
     }
 
-    /// Produce a cached instance-pre handle for the provided component.
+    /// Produce a cached `InstancePre` handle for the provided component using
+    /// the shared linker configuration.
     pub fn instantiate_pre(
         &self,
         component: &Component,