[commitgraph] Tweak and expand documentation.

* Use "number of" phrasing instead of "amount of." * Describe the graph as an index instead of a cache. * Add module-level documentation for `file::commit`, `file::verify`, and `graph::verify`.

Conor Davis committed 5 years ago

Commit ac528671 parent 5569c8f8 files · +27 −20Browse files

Showing the changes to git-commitgraph/src/graph (3 of 8 files). Show all

Unified · Split

3 files

git-commitgraph/src/graph/access.rs +1 −1
git-commitgraph/src/graph/mod.rs +0 −1
git-commitgraph/src/graph/verify.rs +8 −5

git-commitgraph/src/graph/access.rs+1−1

@@ -45,7 +45,7 @@ impl Graph { · 44 unmodified lines
45	Some(self.lookup_by_id(id)?.graph_pos)	45	Some(self.lookup_by_id(id)?.graph_pos)
46	}	46	}
47		47
48	/// Returns the amount of commits stored in this file.	48	/// Returns the number of commits stored in this file.
49	pub fn num_commits(&self) -> u32 {	49	pub fn num_commits(&self) -> u32 {
50	self.files.iter().map(\|f\| f.num_commits()).sum()	50	self.files.iter().map(\|f\| f.num_commits()).sum()
51	}	51	}

git-commitgraph/src/graph/mod.rs+0−1

@@ -1,7 +1,6 @@
1	//! Operations on a complete commit graph.	1	//! Operations on a complete commit graph.
2	mod access;	2	mod access;
3	mod init;	3	mod init;
4	///
5	pub mod verify;	4	pub mod verify;
6		5
7	use crate::file::File;	6	use crate::file::File;

git-commitgraph/src/graph/verify.rs+8−5

+//! Auxiliary types used by graph verification methods.
 use crate::{
     file::{self, commit},
     graph, Graph, GENERATION_NUMBER_MAX,
     TooManyFiles(usize),
 }
-/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()]`.
+/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()`].
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
 pub struct Outcome {
-    /// The longest consecutive amount of commits in a chain of commits.
+    /// The length of the longest path between any two commits in this graph.
     ///
-    /// For example, a repository with 10 commits would have 10 as value.
+    /// For example, this will be `Some(9)` for a commit graph containing 10 linear commits.
+    /// This will be `Some(0)` for a commit graph containing 0 or 1 commits.
+    /// If the longest path length is too large to fit in a [u32], then this will be [None].
     pub longest_path_length: Option<u32>,
-    /// The total amount traversed commits.
+    /// The total number of commits traversed.
     pub num_commits: u32,
-    /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.
+    /// A mapping of `N -> number of commits with N parents`.
     pub parent_counts: BTreeMap<u32, u32>,
 }