Mercurial > hg
changeset 52186:85bff84f0ad5 default
rust-vfs: add docstrings to all VFS methods on the trait
author | Raphaël Gomès <rgomes@octobus.net> |
---|---|
date | Mon, 21 Oct 2024 12:58:40 +0200 |
parents | 8d35941689af |
children | |
files | rust/hg-core/src/vfs.rs |
diffstat | 1 files changed, 31 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- 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; }