feat(logging): improve documentation for file rotation methods

Author: ganeshnj

datadog-log/src/writers.rs

@@ -44,6 +44,10 @@ impl CustomFileAppender {
         chrono::Local::now().format("%Y-%m-%d_%H-%M-%S").to_string()
     }
 
+    /// Build the rotated file path.
+    /// The rotated files names are appended with their rotated at timestamp.
+    /// The file extension is preserved.
+    /// If the file has no extension, the timestamp is appended without a dot.
     fn build_rotated_path(&self, timestamp: &str) -> PathBuf {
         match (self.path.file_stem(), self.path.extension()) {
             (Some(stem), Some(ext)) => {
@@ -63,6 +67,11 @@ impl CustomFileAppender {
         }
     }
 
+    /// Rotate the file if it exceeds the maximum size.
+    /// If the file exceeds the maximum size, it will be renamed to a new file with a timestamp
+    /// and the current file will be closed.
+    /// If the maximum number of files is exceeded, the oldest rotated files will be deleted.
+    /// The rotated files names are appended with their rotated at timestamp.
     fn rotate_if_needed(&mut self) -> io::Result<()> {
         if self.max_size > 0 && self.current_size >= self.max_size {
             self.current_file.flush()?;
@@ -86,6 +95,10 @@ impl CustomFileAppender {
         Ok(())
     }
 
+    /// Cleanup old files when the maximum number of files is exceeded.
+    /// The files are sorted by timestamp (newest first) to ensure we keep the most recent files
+    /// and delete the oldest ones when cleanup is needed.
+    /// The current file is never deleted.
     fn cleanup_old_files(&self, max_files: u64) -> io::Result<()> {
         if max_files == 0 {
             return Ok(());