docs: add doc strings to stupid/tempindex

Author: jpgrayson

src/stupid/tempindex.rs

@@ -1,3 +1,16 @@
+// SPDX-License-Identifier: GPL-2.0-only
+
+//! Context for creating and auto-deleting a temporary index file.
+//!
+//! The temporary index file is created relative to `git_dir`.
+//!
+//! The file name is based on the PID of the StGit process to mitigate the most
+//! egregious name collision scenarios.
+//!
+//! When [`TempIndex`] instance is dropped, it will attempt to delete the temporary
+//! index file. It is okay if the file no longer exists at drop-time, but a panic will
+//! happen if the file exists but removal fails.
+
 use std::path::{Path, PathBuf};
 
 use anyhow::Result;
@@ -8,6 +21,9 @@ pub(crate) struct TempIndex<'repo> {
 }
 
 impl<'repo> TempIndex<'repo> {
+    /// Create new temporary index file relative to `git_dir`.
+    ///
+    /// The temporary index file will be auto-deleted when this value is dropped.
     pub(crate) fn new(git_dir: &'repo Path) -> Result<Self> {
         let pid = std::process::id();
         let filename = PathBuf::from(format!("index-temp-stg-{pid}"));
@@ -20,6 +36,10 @@ impl<'repo> TempIndex<'repo> {
         Ok(Self { git_dir, filename })
     }
 
+    /// Get a reference to the temporary index file name.
+    ///
+    /// This is not a complete path to the file. The file exists relative to the git
+    /// dir.
     pub(crate) fn filename(&self) -> &Path {
         self.filename.as_ref()
     }