lael-labs/gitoxide

git-commitgraph/src/file/access.rs+9−0

 /// Access
 impl File {
+    /// The amount of base graphs that this file depends on.
     pub fn base_graph_count(&self) -> u8 {
         self.base_graph_count
     }
         Commit::new(self, pos)
     }
+    /// The kind of hash used in this File.
+    ///
+    /// Note that it is always conforming to the hash used in the owning repository.
     pub fn hash_kind(&self) -> HashKind {
         HashKind::Sha1
     }
         borrowed::Id::try_from(&self.data[start..start + SHA1_SIZE]).expect("20 bytes SHA1 to be alright")
     }
+    /// Return an iterator over all object hashes stored in the base graph.
     pub fn iter_base_graph_ids(&self) -> impl Iterator<Item = borrowed::Id<'_>> {
         let start = self.base_graphs_list_offset.unwrap_or(0);
         let base_graphs_list = &self.data[start..start + (SHA1_SIZE * usize::from(self.base_graph_count))];
             .map(|bytes| borrowed::Id::try_from(bytes).expect("20 bytes SHA1 to be alright"))
     }
+    /// return an iterator over all commits in this file.
     pub fn iter_commits(&self) -> impl Iterator<Item = Commit<'_>> {
         (0..self.num_commits()).map(move |i| self.commit_at(file::Position(i)))
     }
+    /// Return an iterator over all object hashes stored in this file.
     pub fn iter_ids(&self) -> impl Iterator<Item = borrowed::Id<'_>> {
         (0..self.num_commits()).map(move |i| self.id_at(file::Position(i)))
     }
+    /// Translate the given object hash to its position within this file, if present.
     // copied from git-odb/src/pack/index/access.rs
     pub fn lookup(&self, id: borrowed::Id<'_>) -> Option<file::Position> {
         let first_byte = usize::from(id.first_byte());
         self.fan[255]
     }
+    /// Returns the path to this file.
     pub fn path(&self) -> &Path {
         &self.path
     }

git-commitgraph/src/file/commit.rs+11−12

     slice::Chunks,
 };
+/// The error used in the [`file::commit`][self] module.
 #[derive(thiserror::Error, Debug)]
+#[allow(missing_docs)]
 pub enum Error {
     #[error("commit {0}'s extra edges overflows the commit-graph file's extra edges list")]
     ExtraEdgesListOverflow(owned::Id),
 const NO_PARENT: u32 = 0x7000_0000;
 const EXTENDED_EDGES_MASK: u32 = 0x8000_0000;
+/// A commit as stored in a [`File`].
 pub struct Commit<'a> {
     file: &'a File,
     pos: file::Position,
         self.generation
     }
+    /// Returns an iterator over the parent positions for lookup in the owning [Graph][crate::Graph].
     pub fn iter_parents(&'a self) -> impl Iterator<Item = Result<graph::Position, Error>> + 'a {
         // I didn't find a combinator approach that a) was as strict as ParentIterator, b) supported
         // fuse-after-first-error behavior, and b) was significantly shorter or more understandable
         }
     }
-    // Allow the return value to outlive this Commit object, as it only needs to be bound by the
+    /// Returns the hash of this commit.
-    // lifetime of the parent file.
+    pub fn id(&self) -> borrowed::Id<'a> {
-    pub fn id<'b>(&'b self) -> borrowed::Id<'a>
-    where
-        'a: 'b,
-    {
         self.file.id_at(self.pos)
     }
+    /// Returns the first parent of this commit.
     pub fn parent1(&self) -> Result<Option<graph::Position>, Error> {
         self.iter_parents().next().transpose()
     }
+    /// Returns the position at which this commit is stored in the parent [File].
     pub fn position(&self) -> file::Position {
         self.pos
     }
-    // Allow the return value to outlive this Commit object, as it only needs to be bound by the
+    /// Return the hash of the tree this commit points to.
-    // lifetime of the parent file.
+    pub fn root_tree_id(&self) -> borrowed::Id<'a> {
-    pub fn root_tree_id<'b>(&'b self) -> borrowed::Id<'a>
-    where
-        'a: 'b,
-    {
         self.root_tree_id
     }
 }
     }
 }
+/// An iterator over parents of a [`Commit`].
 pub struct ParentIterator<'a> {
     commit_data: &'a Commit<'a>,
     state: ParentIteratorState<'a>,

git-commitgraph/src/file/init.rs+3−0

 type ChunkId = [u8; 4];
+/// The error used in [`File::at()`].
 #[derive(thiserror::Error, Debug)]
+#[allow(missing_docs)]
 pub enum Error {
     #[error("Commit-graph {:?} chunk contains {from_chunk} base graphs, but commit-graph file header claims {from_header} base graphs", BASE_GRAPHS_LIST_CHUNK_ID.as_bstr())]
     BaseGraphMismatch { from_header: u8, from_chunk: u32 },
 const SENTINEL_CHUNK_ID: ChunkId = [0u8; 4];
 impl File {
+    /// Try to parse the commit graph file at `path`.
     pub fn at(path: impl AsRef<Path>) -> Result<File, Error> {
         Self::try_from(path.as_ref())
     }

git-commitgraph/src/file/mod.rs+9−4

 //! Operations on a single commit-graph file.
 mod access;
+///
 pub mod commit;
+pub use commit::Commit;
 mod init;
+///
 pub mod verify;
 pub use init::Error;
-pub use commit::Commit;
 use filebuffer::FileBuffer;
 use git_hash::SIZE_OF_SHA1_DIGEST as SHA1_SIZE;
 use std::{
 /// A single commit-graph file.
 ///
 /// All operations on a `File` are local to that graph file. Since a commit graph can span multiple
-/// files, all interesting graph operations belong on `Graph`.
+/// files, all interesting graph operations belong on [`Graph`][crate::Graph].
 pub struct File {
     base_graph_count: u8,
     base_graphs_list_offset: Option<usize>,
 /// Commits within a graph file are sorted in lexicographical order by OID; a commit's lexigraphical position
 /// is its position in this ordering. If a commit graph spans multiple files, each file's commits
 /// start at lexigraphical position 0, so it is unique across a single file but is not unique across
-/// the whole commit graph. Each commit also has a graph position (`graph::Position`), which is unique
+/// the whole commit graph. Each commit also has a graph position ([`graph::Position`][crate::graph::Position]),
-/// across the whole commit graph. In order to avoid accidentally mixing lexigraphical positions with graph
+/// which is unique /// across the whole commit graph. In order to avoid accidentally mixing lexigraphical positions with graph
 /// positions, distinct types are used for each.
 #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub struct Position(pub u32);

git-commitgraph/src/file/verify.rs+18−1

     path::Path,
 };
+/// The error used in [`File::traverse()`].
 #[derive(thiserror::Error, Debug)]
+#[allow(missing_docs)]
 pub enum Error<E: std::error::Error + 'static> {
     #[error(transparent)]
     Commit(#[from] file::commit::Error),
     RootTreeId { id: owned::Id, root_tree_id: owned::Id },
 }
+/// The positive result of [`File::traverse()`] providing some statistical information.
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
 pub struct Outcome {
+    /// The highest encountered [`file::Commit`] generation number.
     pub max_generation: u32,
-    pub max_parents: u32,
+    /// The smallest encountered [`file::Commit`] generation number.
     pub min_generation: u32,
+    /// The highest amount parents in a single [`file::Commit`].
+    pub max_parents: u32,
+    /// The total amount of [`commits`][file::Commit] seen in the iteration.
     pub num_commits: u32,
+    /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.
     pub parent_counts: HashMap<u32, u32>,
 }
+/// Verification
 impl File {
+    /// Returns the trailing checksum over the entire content of this file.
     pub fn checksum(&self) -> borrowed::Id<'_> {
         borrowed::Id::try_from(&self.data[self.data.len() - SHA1_SIZE..]).expect("file to be large enough for a hash")
     }
+    /// Traverse all [commits][file::Commit] stored in this file and call `processor(commit) -> Result<(), Error>` on it.
+    ///
+    /// If the `processor` fails, the iteration will be stopped and the entire call results in the respective error.
     pub fn traverse<'a, E, Processor>(&'a self, mut processor: Processor) -> Result<Outcome, Error<E>>
     where
         E: std::error::Error + 'static,
         Ok(stats)
     }
+    /// Assure the [`checksum`][File::checksum()] matches the actual checksum over all content of this file, excluding the trailing
+    /// checksum itself.
+    ///
+    /// Return the actual checksum on success or `(actual checksum, expected checksum)` if there is a mismatch.
     pub fn verify_checksum(&self) -> Result<owned::Id, (owned::Id, owned::Id)> {
         // Even though we could use git_features::hash::bytes_of_file(…), this would require using our own
         // Error type to support io::Error and Mismatch. As we only gain progress, there probably isn't much value