docs(package): explain packaging and dependency workflows

crates/wasmeld-package/src/wit_package.rs

@@ -21,7 +21,9 @@ pub const WIT_PACKAGE_SCHEMA_VERSION: u32 = 1;
 #[derive(Clone, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct WitDependency {
+    /// Package identity in `namespace:name` form.
     pub name: String,
+    /// Exact semantic version encoded by the dependency package.
     pub version: String,
 }
 
@@ -29,32 +31,48 @@ pub struct WitDependency {
 #[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
 #[serde(deny_unknown_fields)]
 pub struct WitPackageMetadata {
+    /// Metadata response schema used by the Registry API.
     pub schema_version: u32,
+    /// Package identity derived from binary WIT contents.
     pub name: String,
+    /// Explicit semantic version derived from binary WIT contents.
     pub version: String,
+    /// SHA-256 digest of the complete binary WIT artifact.
     pub sha256: String,
+    /// Exact direct dependencies embedded in the package.
     pub dependencies: Vec<WitDependency>,
 }
 
 /// Encoded package bytes together with metadata derived from those bytes.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct BuiltWitPackage {
+    /// Metadata derived by decoding the bytes after encoding.
     pub metadata: WitPackageMetadata,
+    /// Standard Component Model binary WIT package.
     pub bytes: Vec<u8>,
 }
 
 /// Errors raised while parsing WIT source or decoding a binary WIT package.
 #[derive(Debug, Error)]
 pub enum WitPackageError {
+    /// WIT source could not be parsed or resolved.
     #[error("failed to parse WIT package at {path}: {message}")]
-    Source { path: PathBuf, message: String },
+    Source {
+        /// Source file or directory passed to the parser.
+        path: PathBuf,
+        /// Parser or dependency-resolution detail.
+        message: String,
+    },
 
+    /// A resolved WIT package could not be encoded.
     #[error("failed to encode WIT package: {0}")]
     Encode(String),
 
+    /// Input bytes are not a standard binary WIT package.
     #[error("invalid binary WIT package: {0}")]
     Decode(String),
 
+    /// The package identity omits the version required by the Registry.
     #[error("WIT package {0} must declare an explicit semantic version")]
     MissingVersion(String),
 }
@@ -64,6 +82,11 @@ pub enum WitPackageError {
 /// The package must declare an explicit semantic version. Dependencies
 /// available through the source path are encoded as Component Model package
 /// references and reported in [`WitPackageMetadata::dependencies`].
+///
+/// # Errors
+///
+/// Returns an error when WIT parsing, dependency resolution, binary encoding,
+/// or post-encode inspection fails.
 pub fn build_wit_package(path: impl AsRef<Path>) -> Result<BuiltWitPackage, WitPackageError> {
     let path = path.as_ref();
     let mut resolve = Resolve::default();
@@ -83,6 +106,11 @@ pub fn build_wit_package(path: impl AsRef<Path>) -> Result<BuiltWitPackage, WitP
 ///
 /// Ordinary WebAssembly Components are rejected even though both formats use a
 /// Component Model binary container.
+///
+/// # Errors
+///
+/// Returns an error if the bytes are malformed, contain a Component instead of
+/// a WIT package, or any package in the direct dependency set lacks a version.
 pub fn inspect_wit_package(bytes: &[u8]) -> Result<WitPackageMetadata, WitPackageError> {
     let decoded = decode(bytes).map_err(|error| WitPackageError::Decode(error.to_string()))?;
     let DecodedWasm::WitPackage(resolve, package) = decoded else {