From b6c82b756d01f686cf0964015e66450027ad4aa6 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Mon, 16 Mar 2026 12:20:28 +0000
Subject: [PATCH] docs: add doc comments for models and task_io utilities

Adds doc comments adhering to RFC 1574 to:
- `TaskNode::create_new_to_disk` (including `# Errors`)
- `default_datetime` (including `# Examples`)
- `current_task_time` (including `# Examples`)

Co-authored-by: matta <37314+matta@users.noreply.github.com>
---
 crates/pebble/src/models.rs  | 21 +++++++++++++++++++++
 crates/pebble/src/task_io.rs | 14 ++++++++++++++
 2 files changed, 35 insertions(+)

diff --git a/crates/pebble/src/models.rs b/crates/pebble/src/models.rs
index b046f95f..cbcd31e9 100644
--- a/crates/pebble/src/models.rs
+++ b/crates/pebble/src/models.rs
@@ -357,6 +357,15 @@ impl TaskNode {
         Ok(())
     }
 
+    /// Creates a new task file on disk.
+    ///
+    /// This method atomically creates a new file at the specified path and writes the task's
+    /// frontmatter and body.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the file already exists, if the serialized content fails to generate,
+    /// or if the file write operation fails.
     pub fn create_new_to_disk(&self) -> Result<()> {
         let content = self.get_content_for_disk()?;
 
@@ -369,6 +378,18 @@ impl TaskNode {
     }
 }
 
+/// Returns the default UTC datetime used across the application.
+///
+/// This serves as a standardized timestamp for missing or uninitialized dates.
+///
+/// # Examples
+///
+/// ```
+/// use chrono::{DateTime, Utc};
+/// use pebble::models::default_datetime;
+///
+/// assert_eq!(default_datetime(), DateTime::<Utc>::UNIX_EPOCH);
+/// ```
 pub fn default_datetime() -> DateTime<Utc> {
     DateTime::<Utc>::UNIX_EPOCH
 }
diff --git a/crates/pebble/src/task_io.rs b/crates/pebble/src/task_io.rs
index 475f8eba..cb088698 100644
--- a/crates/pebble/src/task_io.rs
+++ b/crates/pebble/src/task_io.rs
@@ -1,5 +1,19 @@
 use chrono::{DateTime, Utc};
 
+/// Retrieves the current time in UTC for timestamping tasks.
+///
+/// This function centralizes the acquisition of the current timestamp to ensure
+/// all generated dates in the application are consistently recorded in UTC.
+///
+/// # Examples
+///
+/// ```
+/// use chrono::Utc;
+/// use pebble::task_io::current_task_time;
+///
+/// let now = current_task_time();
+/// assert!(now <= Utc::now());
+/// ```
 pub fn current_task_time() -> DateTime<Utc> {
     Utc::now()
 }