From a86219390e78b35d4f2927da88cd393ac6c50d4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20Lars=C3=A9n?= Date: Sat, 11 Nov 2023 12:54:43 +0100 Subject: [PATCH] Make docs Rust-style --- src/diff.rs | 88 +++++++++++++++++++----------------------- src/file.rs | 42 ++++++++------------ src/index.rs | 22 ++++------- src/object_resolver.rs | 12 ++---- src/objects.rs | 72 +++++++++++++++------------------- src/output.rs | 36 +++++------------ src/status.rs | 10 ++--- src/workspace.rs | 8 +--- tests/test_diff.rs | 10 ++--- 9 files changed, 117 insertions(+), 183 deletions(-) diff --git a/src/diff.rs b/src/diff.rs index ed53407..ed64e46 100644 --- a/src/diff.rs +++ b/src/diff.rs @@ -394,21 +394,19 @@ fn drain_context_into_chunk<'b, 'a: 'b, S: Eq>( chunk_content.extend(context.drain(..).skip(context_to_skip)); } -/** - * Computes a diff between two arbitrary sequences. The typical thing to use would be two lists of - * strings, where each element represents a line. - * - * ``` - * use rut::diff; - * - * let a = "First line\nSecond line\nThird line".split('\n').collect::>(); - * let b = "Second line\nThird line\nFourth line".split('\n').collect::>(); - * - * let diff = diff::diff(&a, &b); - * - * assert_eq!(diff, "-First line\n Second line\n Third line\n+Fourth line\n"); - * ``` - */ +/// Computes a diff between two arbitrary sequences. The typical thing to use would be two lists of +/// strings, where each element represents a line. +/// +/// ``` +/// use rut::diff; +/// +/// let a = "First line\nSecond line\nThird line".split('\n').collect::>(); +/// let b = "Second line\nThird line\nFourth line".split('\n').collect::>(); +/// +/// let diff = diff::diff(&a, &b); +/// +/// assert_eq!(diff, "-First line\n Second line\n Third line\n+Fourth line\n"); +/// ``` pub fn diff(a: &[S], b: &[S]) -> String { let edit_script = edit_script(a, b); let mut result = String::new(); @@ -430,30 +428,28 @@ pub fn diff(a: &[S], b: &[S]) -> String { result } -/** - * Computes an edit script between two arbitrary sequences. - * - * Example: - * ``` - * use rut::diff; - * use rut::diff::{Edit, EditKind}; - * - * let a = "ABC".chars().collect::>(); - * let b = "BBD".chars().collect::>(); - * - * let expected_edits = vec![ - * Edit::deletion('A', 0), - * Edit::equal('B', 1, 0), - * Edit::deletion('C', 2), - * Edit::addition('B', 1), - * Edit::addition('D', 2), - * ]; - * - * let edit_script = diff::edit_script(&a, &b); - * - * assert_eq!(edit_script, expected_edits); - * ``` - */ +/// Computes an edit script between two arbitrary sequences. +/// +/// Example: +/// ``` +/// use rut::diff; +/// use rut::diff::{Edit, EditKind}; +/// +/// let a = "ABC".chars().collect::>(); +/// let b = "BBD".chars().collect::>(); +/// +/// let expected_edits = vec![ +/// Edit::deletion('A', 0), +/// Edit::equal('B', 1, 0), +/// Edit::deletion('C', 2), +/// Edit::addition('B', 1), +/// Edit::addition('D', 2), +/// ]; +/// +/// let edit_script = diff::edit_script(&a, &b); +/// +/// assert_eq!(edit_script, expected_edits); +/// ``` pub fn edit_script(a: &[S], b: &[S]) -> Vec> { let (final_k_value, edit_path_graph) = compute_edit_path_graph(a, b); let reversed_edit_trace = trace_edit_points(final_k_value, edit_path_graph); @@ -577,10 +573,8 @@ fn trace_edit_points(final_k: i32, trace: Vec>) -> Vec<(i32, i32)> { edit_points } -/** - * Compute the previous k-value in the edit path graph. This function is optimized for - * understandability rather than performance, it can easily be compressed into a single condition. - */ +/// Compute the previous k-value in the edit path graph. This function is optimized for +/// understandability rather than performance, it can easily be compressed into a single condition. fn compute_previous_k(k: i32, d: i32, v: &[usize]) -> i32 { if k == -d { // the previous move must have been from a larger k as abs(k) <= d @@ -631,17 +625,13 @@ fn compute_edit_script( edits } -/** - * Get a value from the vector with support for negative indexing. - */ +/// Get a value from the vector with support for negative indexing. fn get(iterable: &[S], index: i32) -> &S { let adjusted_index = adjust_index(iterable, index); iterable.get(adjusted_index).unwrap() } -/** - * Set a value in the vector with support for negative indexing. - */ +/// Set a value in the vector with support for negative indexing. fn set(iterable: &mut [S], index: i32, value: S) { let adjusted_index = adjust_index(iterable, index); iterable[adjusted_index] = value diff --git a/src/file.rs b/src/file.rs index fe587b8..0368855 100644 --- a/src/file.rs +++ b/src/file.rs @@ -16,10 +16,8 @@ pub fn read_file>(path: P) -> io::Result> { Ok(bytes) } -/** - * Atomically write to a file by first writing to a temporary file and then renaming it to the - * target file. - */ +/// Atomically write to a file by first writing to a temporary file and then renaming it to the +/// target file. pub fn atomic_write(path: &Path, content: &[u8]) -> io::Result<()> { let mut buffer_file = PathBuf::from(path); let buffer_file_extension = format!( @@ -35,23 +33,19 @@ pub fn atomic_write(path: &Path, content: &[u8]) -> io::Result<()> { fs::rename(&buffer_file, path) } -/** - * Create a new file and write the content to it. Fail if the file already exists. - */ +/// Create a new file and write the content to it. Fail if the file already exists. pub fn create_file(path: &Path, content: &[u8]) -> io::Result<()> { let mut file = OpenOptions::new().create_new(true).write(true).open(path)?; file.write_all(content) } -/** - * Struct that enables synchronized atomic writing to files. On acquiring with a lock with - * [`LockFile::acquire`] an empty lockfile is created in the file system. You can then use - * [`LockFile::write`] to write content to the lockfile. - * - * When the [`LockFile`] goes out of scope, the lockfile itself is renamed to the target file for - * which the lock was acquired. Renames are atomic operations, so there is no risk that someone - * reading the file without acquiring the lock gets a partially written result. - */ +/// Struct that enables synchronized atomic writing to files. On acquiring with a lock with +/// [`LockFile::acquire`] an empty lockfile is created in the file system. You can then use +/// [`LockFile::write`] to write content to the lockfile. +/// +/// When the [`LockFile`] goes out of scope, the lockfile itself is renamed to the target file for +/// which the lock was acquired. Renames are atomic operations, so there is no risk that someone +/// reading the file without acquiring the lock gets a partially written result. pub struct LockFile { path: PathBuf, lockfile: File, @@ -195,12 +189,10 @@ pub trait AsVec { fn as_vec(&self) -> Vec; } -/** - * A resource backed by a lockfile. The final write is atomically transferred to the original file - * when this struct is destroyed. - * - * Do note that any intermediate writes are simply discarded. - */ +/// A resource backed by a lockfile. The final write is atomically transferred to the original file +/// when this struct is destroyed. +/// +/// Do note that any intermediate writes are simply discarded. pub struct LockFileResource> { lockfile: LockFile, resource: T, @@ -211,10 +203,8 @@ impl> LockFileResource { LockFileResource { lockfile, resource } } - /** - * Write the resource to the lockfile. The final write to the lockfile are committed to the - * original resource once this struct is destroyed. - */ + /// Write the resource to the lockfile. The final write to the lockfile are committed to the + /// original resource once this struct is destroyed. pub fn write(&mut self) -> io::Result<()> { self.lockfile.write(&self.resource.as_vec()) } diff --git a/src/index.rs b/src/index.rs index b6678ad..67561b9 100644 --- a/src/index.rs +++ b/src/index.rs @@ -175,14 +175,12 @@ impl Index { } } - /** - * We need to discard any new entries that conflict with existing ones. For example, given an - * existing entry `file.txt`, adding a new entry for `file.txt/nested.txt` (i.e. there's now a - * directory called `file.txt` with a file `nested.txt` in it), we need to remove `file.txt`. - * - * Similarly, given an existing entry `nested/dir/file.txt` and adding an entry `nested`, we - * expect `nested/dir/file.txt` to be removed from the index. - */ + /// We need to discard any new entries that conflict with existing ones. For example, given an + /// existing entry `file.txt`, adding a new entry for `file.txt/nested.txt` (i.e. there's now a + /// directory called `file.txt` with a file `nested.txt` in it), we need to remove `file.txt`. + /// + /// Similarly, given an existing entry `nested/dir/file.txt` and adding an entry `nested`, we + /// expect `nested/dir/file.txt` to be removed from the index. fn discard_conflicting_entries>(&mut self, path: P) { self.remove_directory(&path); for parent in path.as_ref().ancestors() { @@ -199,16 +197,12 @@ impl Index { } } - /** - * Check whether a path exists as an entry in the index. - */ + /// Check whether a path exists as an entry in the index. pub fn has_entry>(&self, path: P) -> bool { self.entries.contains_key(path.as_ref()) } - /** - * Check whether a path is a tracked directory. - */ + /// Check whether a path is a tracked directory. pub fn is_tracked_directory>(&self, path: P) -> bool { self.directories.contains_key(path.as_ref()) } diff --git a/src/object_resolver.rs b/src/object_resolver.rs index b110305..32907a6 100644 --- a/src/object_resolver.rs +++ b/src/object_resolver.rs @@ -39,9 +39,7 @@ impl<'a> ObjectResolver<'a> { Ok(ObjectResolver::new(root_tree, &repository.database)) } - /** - * Find a blob by its path, relative to the root tree of this ObjectResolver. - */ + /// Find a blob by its path, relative to the root tree of this ObjectResolver. pub fn find_blob_by_path(&mut self, path: &Path) -> io::Result { if let Some(blob) = self.blobs.get(path) { return Ok(blob.clone()); @@ -73,9 +71,7 @@ impl<'a> ObjectResolver<'a> { self.find_blob_in_subtree(parent_path, remaining_path) } - /** - * Recursively find a blob in a subtree. Cache any trees found along the way. - */ + /// Recursively find a blob in a subtree. Cache any trees found along the way. fn find_blob_in_subtree( &mut self, parent_path: &Path, @@ -104,9 +100,7 @@ impl<'a> ObjectResolver<'a> { self.find_blob_in_tree_(¤t_path, &curent_remaining_path) } - /** - * Get a blob assuming its parent tree is already cached. - */ + /// Get a blob assuming its parent tree is already cached. fn get_blob(&mut self, blob_path: &Path) -> io::Result { let file_name = blob_path.file_name().unwrap().to_str().unwrap(); let tree = &self.trees[blob_path.parent().unwrap()]; diff --git a/src/objects.rs b/src/objects.rs index 11c7bdf..c569c7a 100644 --- a/src/objects.rs +++ b/src/objects.rs @@ -25,62 +25,54 @@ pub trait GitObject<'a> { fn to_object_format(&self) -> Vec; } -/** - * A Git object id is the sha1 hash of the object's content, which is represented as a 40 byte - * hexadecimal string. This struct encapsulates this concept and provides some utility methods - * related to common operations on object ids, such as finding out the filepath in the object - * database. - */ +/// A Git object id is the sha1 hash of the object's content, which is represented as a 40 byte +/// hexadecimal string. This struct encapsulates this concept and provides some utility methods +/// related to common operations on object ids, such as finding out the filepath in the object +/// database. #[derive(Debug, PartialEq, Eq, Clone)] pub struct ObjectId { bytes: Vec, } impl ObjectId { - /** - * Turn a hexadecimal string into an ObjectId. This is the inverse of to_string(). - * - * # Examples - * ``` - * use rut::objects::ObjectId; - * - * let id = ObjectId::from_sha("a94a8fe5ccb19ba61c4c0873d391e987982fbbd3").unwrap(); - * assert_eq!(id.to_string(), "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"); - * ``` - */ + /// Turn a hexadecimal string into an ObjectId. This is the inverse of to_string(). + /// + /// # Examples + /// ``` + /// use rut::objects::ObjectId; + /// + /// let id = ObjectId::from_sha("a94a8fe5ccb19ba61c4c0873d391e987982fbbd3").unwrap(); + /// assert_eq!(id.to_string(), "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"); + /// ``` pub fn from_sha(s: &str) -> Result { let bytes = hex::from_hex_string(s).map_err(|e| e.to_string())?; Self::from_sha_bytes(&bytes) } - /** - * Turn a string that is the utf8 encoded version of a sha1 hash into an ObjectId. - * - * # Examples - * ``` - * use rut::objects::ObjectId; - * - * let bytes = "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3".as_bytes(); - * let id = ObjectId::from_utf8_encoded_sha(bytes).unwrap(); - * assert_eq!(id.to_string(), "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"); - * ``` - */ + /// Turn a string that is the utf8 encoded version of a sha1 hash into an ObjectId. + /// + /// # Examples + /// ``` + /// use rut::objects::ObjectId; + /// + /// let bytes = "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3".as_bytes(); + /// let id = ObjectId::from_utf8_encoded_sha(bytes).unwrap(); + /// assert_eq!(id.to_string(), "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3"); + /// ``` pub fn from_utf8_encoded_sha(bytes: &[u8]) -> Result { let s = str::from_utf8(bytes).map_err(|e| e.to_string())?; Self::from_sha(s) } - /** - * Turn bytes into an ObjectId. This is the inverse of bytes(). - * - * # Examples - * ``` - * use rut::objects::ObjectId; - * - * let bytes = "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3".as_bytes(); - * let id = ObjectId::from_sha_bytes(bytes).unwrap(); - * assert_eq!(id.bytes(), bytes); - */ + /// Turn bytes into an ObjectId. This is the inverse of bytes(). + /// + /// # Examples + /// ``` + /// use rut::objects::ObjectId; + /// + /// let bytes = "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3".as_bytes(); + /// let id = ObjectId::from_sha_bytes(bytes).unwrap(); + /// assert_eq!(id.bytes(), bytes); pub fn from_sha_bytes(bytes: &[u8]) -> Result { let unhexlified_bytes = if bytes.len() == 20 { hex::unhexlify(bytes) diff --git a/src/output.rs b/src/output.rs index 59eda57..e03f117 100644 --- a/src/output.rs +++ b/src/output.rs @@ -1,47 +1,31 @@ use std::io; -/** - * Abstraction of an output writer used by Rut commands to write status messages. - */ +/// Abstraction of an output writer used by Rut commands to write status messages. pub trait OutputWriter { - /** - * Write the content to the output. - */ + /// Write the content to the output. fn write(&mut self, content: String) -> io::Result<&mut dyn OutputWriter>; - /** - * Write the content to the output and append a linefeed. - */ + /// Write the content to the output and append a linefeed. fn writeln(&mut self, content: String) -> io::Result<&mut dyn OutputWriter> { self.write(content)?.linefeed() } - /** - * Convenience method to write a linefeed to the output. - */ + /// Convenience method to write a linefeed to the output. fn linefeed(&mut self) -> io::Result<&mut dyn OutputWriter> { self.write(String::from("\n")) } - /** - * Change the color of the output. - */ + /// Change the color of the output. fn set_color(&mut self, color: Color) -> io::Result<&mut dyn OutputWriter>; - /** - * Change the style of the output. - */ + /// Change the style of the output. fn set_style(&mut self, stye: Style) -> io::Result<&mut dyn OutputWriter>; - /** - * Reset all output formatting. - */ + /// Reset all output formatting. fn reset_formatting(&mut self) -> io::Result<&mut dyn OutputWriter>; } -/** - * A color used by an OutputWriter. - */ +/// A color used by an OutputWriter. pub enum Color { Red, Green, @@ -49,9 +33,7 @@ pub enum Color { Brown, } -/** - * A style used by an OutputWriter. - */ +/// A style used by an OutputWriter. pub enum Style { Bold, Normal, diff --git a/src/status.rs b/src/status.rs index 29264ec..0f12a6a 100644 --- a/src/status.rs +++ b/src/status.rs @@ -467,12 +467,10 @@ fn resolve_unstaged_modifications<'a>( }) } -/** - * Returns true if the file at the given path has been modified since the last commit. - * - * Side effect: Updates the index with new mtimes if they've been updatet without the content being - * changed. - */ +/// Returns true if the file at the given path has been modified since the last commit. +/// +/// Side effect: Updates the index with new mtimes if they've been updatet without the content being +/// changed. fn is_modified(absolute_path: &Path, tracked_path: &Path, index: &mut Index) -> io::Result { let is_modified = if let Some(index_entry) = index.get_mut(tracked_path) { let metadata = fs::metadata(absolute_path)?; diff --git a/src/workspace.rs b/src/workspace.rs index 2c90d7d..1655aed 100644 --- a/src/workspace.rs +++ b/src/workspace.rs @@ -488,16 +488,12 @@ impl Worktree { } } - /** - * Absolute path to the root of the worktree. - */ + /// Absolute path to the root of the worktree. pub fn root(&self) -> &Path { &self.root } - /** - * Return the path relative to the root of this worktree. - */ + /// Return the path relative to the root of this worktree. pub fn relativize_path>(&self, absolute_path: P) -> PathBuf { let relative_path = absolute_path .as_ref() diff --git a/tests/test_diff.rs b/tests/test_diff.rs index a00eb22..3d7d403 100644 --- a/tests/test_diff.rs +++ b/tests/test_diff.rs @@ -221,12 +221,10 @@ fn create_committed_file_with_staged_changes( Ok(expected_output) } -/** - * When writing tiny files in tests, there may not be enough time between writes to make for - * different timestamps between the writes. We therefore need to sleep a tiny amount before - * making a new write where there is a necessity to have it happen "strictly after" a previous - * write to the same file. - */ +/// When writing tiny files in tests, there may not be enough time between writes to make for +/// different timestamps between the writes. We therefore need to sleep a tiny amount before +/// making a new write where there is a necessity to have it happen "strictly after" a previous +/// write to the same file. fn wait_for_new_timestamp() { thread::sleep(std::time::Duration::from_millis(10)); }