docs: Add missing doc comments to public utility APIs

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
 }

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()
 }