add documented rust file example

examples/documented_rust_file.rs

@@ -0,0 +1,146 @@
+//! Canonical documented Rust file example.
+//!
+//! This example exists as a style reference for the repository. It shows the
+//! minimum level of explanation expected in a real source file:
+//!
+//! - module-level documentation
+//! - public API rustdoc
+//! - doctest examples
+//! - field-level documentation
+//! - short rationale comments for non-obvious decisions
+//! - a small internal test module
+//!
+//! The implementation itself is intentionally simple. The point is the shape of
+//! the file, not the sophistication of the algorithm.
+
+use std::collections::VecDeque;
+
+/// Rolling event log with a fixed visible capacity.
+///
+/// The oldest entries fall off once capacity is reached. This is a common shape
+/// in terminal UIs and tracing tools where recent context matters most.
+///
+/// # Example
+/// ```rust
+/// let mut log = documented_rust_file::RollingLog::new(2);
+/// log.push("alpha");
+/// log.push("beta");
+/// log.push("gamma");
+/// assert_eq!(log.entries(), ["beta", "gamma"]);
+/// ```
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RollingLog {
+    /// Maximum number of entries kept in memory.
+    capacity: usize,
+    /// Recent entries ordered from oldest to newest.
+    entries: VecDeque<String>,
+}
+
+impl RollingLog {
+    /// Creates a new rolling log with the given capacity.
+    ///
+    /// # Panics
+    ///
+    /// Panics if `capacity` is zero.
+    ///
+    /// # Example
+    /// ```rust
+    /// let log = documented_rust_file::RollingLog::new(3);
+    /// assert_eq!(log.len(), 0);
+    /// ```
+    pub fn new(capacity: usize) -> Self {
+        assert!(capacity > 0, "rolling log capacity must be non-zero");
+
+        Self {
+            capacity,
+            entries: VecDeque::with_capacity(capacity),
+        }
+    }
+
+    /// Appends one entry, evicting the oldest entry when full.
+    ///
+    /// # Example
+    /// ```rust
+    /// let mut log = documented_rust_file::RollingLog::new(2);
+    /// log.push("first");
+    /// log.push("second");
+    /// assert_eq!(log.len(), 2);
+    /// ```
+    pub fn push(&mut self, entry: impl Into<String>) {
+        // Rationale: trim before push so capacity is never exceeded, even
+        // transiently, which keeps later invariants and tests straightforward.
+        if self.entries.len() == self.capacity {
+            self.entries.pop_front();
+        }
+        self.entries.push_back(entry.into());
+    }
+
+    /// Returns the number of currently stored entries.
+    pub fn len(&self) -> usize {
+        self.entries.len()
+    }
+
+    /// Returns `true` when there are no entries.
+    pub fn is_empty(&self) -> bool {
+        self.entries.is_empty()
+    }
+
+    /// Returns the stored entries as a freshly owned vector.
+    ///
+    /// Rationale: this returns owned `String`s instead of references because it
+    /// keeps the example easy to copy into UI code, serialization, or tests.
+    pub fn entries(&self) -> Vec<String> {
+        self.entries.iter().cloned().collect()
+    }
+
+    /// Returns the most recent entry, if any.
+    pub fn newest(&self) -> Option<&str> {
+        self.entries.back().map(String::as_str)
+    }
+}
+
+/// Formats a small status line suitable for logs or demos.
+///
+/// # Example
+/// ```rust
+/// assert_eq!(documented_rust_file::format_status("sync", true), "sync: ok");
+/// assert_eq!(documented_rust_file::format_status("sync", false), "sync: pending");
+/// ```
+pub fn format_status(label: &str, done: bool) -> String {
+    let suffix = if done { "ok" } else { "pending" };
+    format!("{label}: {suffix}")
+}
+
+/// Small executable entry point so Cargo can build this file as an example.
+fn main() {
+    let mut log = RollingLog::new(2);
+    log.push(format_status("example", true));
+
+    // Printing one line keeps the example executable visible without distracting
+    // from the file's main purpose as a documentation template.
+    if let Some(line) = log.newest() {
+        println!("{line}");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{RollingLog, format_status};
+
+    #[test]
+    fn rolling_log_evicts_oldest_entry() {
+        let mut log = RollingLog::new(2);
+        log.push("alpha");
+        log.push("beta");
+        log.push("gamma");
+
+        assert_eq!(log.entries(), ["beta", "gamma"]);
+        assert_eq!(log.newest(), Some("gamma"));
+    }
+
+    #[test]
+    fn status_helper_is_stable() {
+        assert_eq!(format_status("build", true), "build: ok");
+        assert_eq!(format_status("build", false), "build: pending");
+    }
+}