doc: add documentation

README.md

@@ -1 +1,64 @@
-# rust-sdk
+# Eppo Rust SDK
+
+[Eppo](https://www.geteppo.com/) is a modular flagging and experimentation analysis tool. Eppo's Rust SDK is designed to facilitate assignments in multi-user server-side contexts. You will need an Eppo account before proceeding.
+
+## Features
+
+- Feature gates
+- Kill switches
+- Progressive rollouts
+- A/B/n experiments
+- Mutually exclusive experiments (Layers)
+- Dynamic configuration
+
+## Installation
+
+Add it with cargo:
+```sh
+cargo add eppo
+```
+
+Or add it to `Cargo.toml` manually:
+```toml
+[dependencies]
+eppo = "0.1.0"
+```
+
+## Quick Start
+
+Initialize an instance of Eppo's client. Once initialized, the client can be used to make assignments in your app.
+
+### Initialize Client
+
+```rust
+use eppo::ClientConfig;
+
+let mut client = ClientConfig::from_api_key("api-key").to_client();
+client.start_poller_thread();
+```
+
+### Assign Anywhere
+
+```rust
+let user = get_current_user();
+
+let assignment = client.get_assignment(
+    "show-new-feature",
+    &user.id,
+    &user.attributes,
+);
+```
+
+## Assignment Logger
+
+Pass a logging callback function to the `assignment_logger` method in `ClientConfig` when initializing the SDK to capture assignment data for analysis.
+
+```rust
+struct MyAssignmentLogger;
+
+impl AssignmentLogger for MyAssignmentLogger {
+    fn log_assignment(&self, event: AssignmentEvent) {
+        // Implement assignment logging logic here
+    }
+}
+```

examples/simple/main.rs

@@ -1,10 +1,16 @@
 use std::collections::HashMap;
 
 pub fn main() -> eppo::Result<()> {
+    // Configure env_logger to see Eppo SDK logs.
     env_logger::Builder::from_env(env_logger::Env::new().default_filter_or("eppo")).init();
 
-    let api_key = std::env::var("EPPO_API_KEY").unwrap();
-    let mut client = eppo::ClientConfig::from_api_key(api_key).to_client();
+    let api_key =
+        std::env::var("EPPO_API_KEY").expect("EPPO_API_KEY env variable should contain API key");
+    let mut client = eppo::ClientConfig::from_api_key(api_key)
+        .assignment_logger(|event| {
+            println!("Logging assignment event: {:?}", event);
+        })
+        .to_client();
 
     // Start a poller thread to fetch configuration from the server.
     let poller = client.start_poller_thread()?;

src/assignment_logger.rs

@@ -4,22 +4,65 @@ use serde::{Deserialize, Serialize};
 
 use crate::SubjectAttributes;
 
+/// Represents an event capturing the assignment of a feature flag to a subject and its logging
+/// details.
 #[derive(Debug, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct AssignmentEvent {
+    /// The key of the feature flag being assigned.
     pub feature_flag: String,
+    /// The key of the allocation that the subject was assigned to.
     pub allocation: String,
+    /// The key of the experiment associated with the assignment.
     pub experiment: String,
+    /// The specific variation assigned to the subject.
     pub variation: String,
+    /// The key identifying the subject receiving the assignment.
     pub subject: String,
+    /// Custom attributes of the subject relevant to the assignment.
     pub subject_attributes: SubjectAttributes,
+    /// The timestamp indicating when the assignment event occurred.
     pub timestamp: String,
+    /// Additional metadata such as SDK language and version.
     pub meta_data: HashMap<String, String>,
+    /// Additional user-defined logging fields for capturing extra information related to the
+    /// assignment.
     #[serde(flatten)]
     pub extra_logging: HashMap<String, String>,
 }
 
+/// A trait for logging assignment events to your storage system. Implementations should handle
+/// persisting assignment events for analytics and tracking purposes.
 pub trait AssignmentLogger {
+    /// Logs the assignment event to the storage system.
+    ///
+    /// # Arguments
+    ///
+    /// * `event` - An [`AssignmentEvent`] to be logged.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use eppo::{AssignmentLogger, AssignmentEvent};
+    /// struct MyAssignmentLogger;
+    ///
+    /// impl AssignmentLogger for MyAssignmentLogger {
+    ///     fn log_assignment(&self, event: AssignmentEvent) {
+    ///         // Implement assignment logging logic here
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// # Errors
+    ///
+    /// This method should not return errors and should not panic.
+    /// Errors that occur during logging should be handled internally within the implementation.
+    ///
+    /// # Notes
+    ///
+    /// This method is called before returning assignment to the caller, so it is important that
+    /// `log_assignment` does not block the calling thread to prevent performance implications and
+    /// delays in returning assignments.
     fn log_assignment(&self, event: AssignmentEvent);
 }