feat: add docs (#2)

Author: ssddOnTop

src/config.rs

@@ -1,20 +1,31 @@
+//! Configuration types for the registry server.
+
 use std::path::PathBuf;
 
+/// Storage backend for registry data.
 #[derive(Debug, Clone)]
 pub enum StorageBackend {
+    /// In-memory storage (data lost when server stops).
     Memory,
+    /// Temporary directory storage (cleaned up automatically).
     TempDir,
+    /// Persistent directory storage at a specific path.
     Directory(PathBuf),
 }
 
+/// Configuration for the registry server.
 #[derive(Debug, Clone)]
 pub struct RegistryConfig {
+    /// Storage backend to use.
     pub storage: StorageBackend,
+    /// Port to bind to (None for random port).
     pub port: Option<u16>,
+    /// Host address to bind to.
     pub host: String,
 }
 
 impl RegistryConfig {
+    /// Creates a new configuration with the specified storage backend.
     pub fn new(storage: StorageBackend) -> Self {
         Self {
             storage,
@@ -23,23 +34,28 @@ impl RegistryConfig {
         }
     }
 
+    /// Creates a configuration with in-memory storage.
     pub fn memory() -> Self {
         Self::new(StorageBackend::Memory)
     }
 
+    /// Creates a configuration with temporary directory storage.
     pub fn temp_dir() -> Self {
         Self::new(StorageBackend::TempDir)
     }
 
+    /// Creates a configuration with directory storage at the specified path.
     pub fn directory(path: PathBuf) -> Self {
         Self::new(StorageBackend::Directory(path))
     }
 
+    /// Sets a specific port for the server to bind to.
     pub fn with_port(mut self, port: u16) -> Self {
         self.port = Some(port);
         self
     }
 
+    /// Sets the host address for the server to bind to.
     pub fn with_host(mut self, host: impl Into<String>) -> Self {
         self.host = host.into();
         self

src/error.rs

@@ -1,7 +1,11 @@
+//! Error types for the registry.
+
 use thiserror::Error;
 
+/// Result type alias for registry operations.
 pub type Result<T> = std::result::Result<T, RegistryError>;
 
+/// Errors that can occur during registry operations.
 #[derive(Error, Debug)]
 pub enum RegistryError {
     #[error("IO error: {0}")]

src/lib.rs

@@ -1,3 +1,22 @@
+//! A minimal, OCI-compliant container registry for testing and development.
+//!
+//! This crate provides a simple way to spin up a local container registry for testing
+//! Docker/OCI container workflows without external dependencies.
+//!
+//! # Examples
+//!
+//! ```no_run
+//! use registry_testkit::{RegistryServer, RegistryConfig};
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let config = RegistryConfig::memory();
+//!     let server = RegistryServer::new(config).await?;
+//!     println!("Registry running at {}", server.url());
+//!     Ok(())
+//! }
+//! ```
+
 pub mod config;
 pub mod error;
 pub mod server;

src/server.rs

@@ -1,3 +1,5 @@
+//! OCI-compliant registry server implementation.
+
 use crate::config::RegistryConfig;
 use crate::error::Result;
 use crate::storage::{create_storage, ManifestEntry, Storage};
@@ -38,12 +40,29 @@ struct UploadParams {
     digest: Option<String>,
 }
 
+/// The main registry server.
+///
+/// Implements an OCI-compliant container registry that can be used for
+/// testing Docker/container workflows.
 pub struct RegistryServer {
     addr: SocketAddr,
     _handle: tokio::task::JoinHandle<()>,
 }
 
 impl RegistryServer {
+    /// Creates and starts a new registry server with the given configuration.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use registry_testkit::{RegistryServer, RegistryConfig};
+    ///
+    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+    /// let config = RegistryConfig::memory();
+    /// let server = RegistryServer::new(config).await?;
+    /// # Ok(())
+    /// # }
+    /// ```
     pub async fn new(config: RegistryConfig) -> Result<Self> {
         let storage = create_storage(&config.storage).await?;
 
@@ -87,14 +106,28 @@ impl RegistryServer {
         })
     }
 
+    /// Returns the socket address the server is bound to.
     pub fn addr(&self) -> SocketAddr {
         self.addr
     }
 
+    /// Returns the full URL of the registry server.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use registry_testkit::{RegistryServer, RegistryConfig};
+    /// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+    /// # let server = RegistryServer::new(RegistryConfig::memory()).await?;
+    /// println!("Registry URL: {}", server.url());
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn url(&self) -> String {
         format!("http://{}", self.addr)
     }
 
+    /// Returns the port number the server is listening on.
     pub fn port(&self) -> u16 {
         self.addr.port()
     }

src/storage.rs

@@ -1,3 +1,5 @@
+//! Storage backends for registry data.
+
 use crate::config::StorageBackend;
 use crate::error::{RegistryError, Result};
 use async_trait::async_trait;
@@ -7,23 +9,35 @@ use std::sync::Arc;
 use tokio::fs;
 use tokio::sync::RwLock;
 
+/// Container image manifest with metadata.
 #[derive(Clone)]
 pub struct ManifestEntry {
+    /// Raw manifest data.
     pub data: Vec<u8>,
+    /// Content type of the manifest.
     pub content_type: String,
 }
 
+/// Trait for storage backends handling registry data.
 #[async_trait]
 pub trait Storage: Send + Sync {
+    /// Stores a manifest with the given key.
     async fn store_manifest(&self, key: String, entry: ManifestEntry) -> Result<()>;
+    /// Retrieves a manifest by key.
     async fn get_manifest(&self, key: &str) -> Result<Option<ManifestEntry>>;
+    /// Stores a blob with the given digest.
     async fn store_blob(&self, digest: String, data: Vec<u8>) -> Result<()>;
+    /// Retrieves a blob by digest.
     async fn get_blob(&self, digest: &str) -> Result<Option<Vec<u8>>>;
+    /// Creates a new upload session with the given UUID.
     async fn create_upload(&self, uuid: String) -> Result<()>;
+    /// Appends data to an existing upload session.
     async fn append_upload(&self, uuid: &str, data: &[u8]) -> Result<()>;
+    /// Finalizes an upload session and returns the complete data.
     async fn finish_upload(&self, uuid: &str) -> Result<Option<Vec<u8>>>;
 }
 
+/// In-memory storage implementation.
 #[derive(Default)]
 pub struct MemoryStorage {
     manifests: Arc<RwLock<HashMap<String, ManifestEntry>>>,
@@ -32,6 +46,7 @@ pub struct MemoryStorage {
 }
 
 impl MemoryStorage {
+    /// Creates a new in-memory storage backend.
     pub fn new() -> Self {
         Self::default()
     }
@@ -76,12 +91,14 @@ impl Storage for MemoryStorage {
     }
 }
 
+/// Disk-based storage implementation.
 pub struct DiskStorage {
     base_path: PathBuf,
     _temp_dir: Option<tempfile::TempDir>,
 }
 
 impl DiskStorage {
+    /// Creates a new disk storage backend at the specified path.
     pub async fn new(path: PathBuf) -> Result<Self> {
         fs::create_dir_all(&path).await?;
         fs::create_dir_all(path.join("manifests")).await?;
@@ -94,6 +111,7 @@ impl DiskStorage {
         })
     }
 
+    /// Creates a new temporary disk storage backend.
     pub async fn temp() -> Result<Self> {
         let temp_dir = tempfile::tempdir()?;
         let path = temp_dir.path().to_path_buf();
@@ -211,6 +229,7 @@ impl Storage for DiskStorage {
     }
 }
 
+/// Creates a storage backend from the given configuration.
 pub async fn create_storage(backend: &StorageBackend) -> Result<Arc<dyn Storage>> {
     match backend {
         StorageBackend::Memory => Ok(Arc::new(MemoryStorage::new())),