changeset 52186:85bff84f0ad5

rust-vfs: add docstrings to all VFS methods on the trait

--- a/rust/hg-core/src/vfs.rs	Thu Oct 10 15:54:45 2024 +0200
+++ b/rust/hg-core/src/vfs.rs	Mon Oct 21 12:58:40 2024 +0200
@@ -519,30 +519,60 @@
 /// filesystem layer (like passing one from Python).
 pub trait Vfs: Sync + Send + DynClone {
     // TODO make `open` readonly and make `open_read` an `open_write`
+    /// Open a [`VfsFile::Normal`] for writing and reading the file at
+    /// `filename`, relative to this VFS's root.
     fn open(&self, filename: &Path) -> Result<VfsFile, HgError>;
+    /// Open a [`VfsFile::Normal`] for reading the file at `filename`,
+    /// relative to this VFS's root.
     fn open_read(&self, filename: &Path) -> Result<VfsFile, HgError>;
+    /// Open a [`VfsFile::Normal`] for reading and writing the file at
+    /// `filename`, relative to this VFS's root. This file will be checked
+    /// for an ambiguous mtime on [`drop`]. See [`is_filetime_ambiguous`].
     fn open_check_ambig(&self, filename: &Path) -> Result<VfsFile, HgError>;
+    /// Create a [`VfsFile::Normal`] for reading and writing the file at
+    /// `filename`, relative to this VFS's root. If the file already exists,
+    /// it will be truncated to 0 bytes.
     fn create(
         &self,
         filename: &Path,
         check_ambig: bool,
     ) -> Result<VfsFile, HgError>;
-    /// Must truncate the new file if exist
+    /// Create a [`VfsFile::Atomic`] for reading and writing the file at
+    /// `filename`, relative to this VFS's root. If the file already exists,
+    /// it will be truncated to 0 bytes.
     fn create_atomic(
         &self,
         filename: &Path,
         check_ambig: bool,
     ) -> Result<VfsFile, HgError>;
+    /// Return the total file size in bytes of the open `file`. Errors are
+    /// usual IO errors (invalid file handle, permissions, etc.)
     fn file_size(&self, file: &VfsFile) -> Result<u64, HgError>;
+    /// Return `true` if `filename` exists relative to this VFS's root. Errors
+    /// will coerce to `false`, to this also returns `false` if there are
+    /// IO problems. This is fine because any operation that actually tries
+    /// to do anything with this path will get the same error.
     fn exists(&self, filename: &Path) -> bool;
+    /// Remove the file at `filename` relative to this VFS's root. Errors
+    /// are the usual IO errors (lacking permission, file does not exist, etc.)
     fn unlink(&self, filename: &Path) -> Result<(), HgError>;
+    /// Rename the file `from` to `to`, both relative to this VFS's root.
+    /// Errors are the usual IO errors (lacking permission, file does not
+    /// exist, etc.). If `check_ambig` is `true`, the VFS will check for an
+    /// ambiguous mtime on rename. See [`is_filetime_ambiguous`].
     fn rename(
         &self,
         from: &Path,
         to: &Path,
         check_ambig: bool,
     ) -> Result<(), HgError>;
+    /// Rename the file `from` to `to`, both relative to this VFS's root.
+    /// Errors are the usual IO errors (lacking permission, file does not
+    /// exist, etc.). If `check_ambig` is passed, the VFS will check for an
+    /// ambiguous mtime on rename. See [`is_filetime_ambiguous`].
     fn copy(&self, from: &Path, to: &Path) -> Result<(), HgError>;
+    /// Returns the absolute root path of this VFS, relative to which all
+    /// operations are done.
     fn base(&self) -> &Path;
 }