[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 (8 of 8 files). Show all

Unified · Split

8 files

git-commitgraph/src/file/access.rs +1 −1
git-commitgraph/src/file/commit.rs +1 −0
git-commitgraph/src/file/mod.rs +0 −2
git-commitgraph/src/file/verify.rs +5 −4
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/lib.rs +11 −6

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

@@ -9,7 +9,7 @@ use std::{ · 8 unmodified lines
9	9
10	10	/// Access
11	11	impl File {
12		− /// The amount of base graphs that this file depends on.
	12	+ /// The number of base graphs that this file depends on.
13	13	pub fn base_graph_count(&self) -> u8 {
14	14	self.base_graph_count
15	15	}

git-commitgraph/src/file/commit.rs+1−0

@@ -1,3 +1,4 @@
	1	+//! Low-level operations on individual commits.
1	2	use crate::{
2	3	file::{self, File},
3	4	graph,

git-commitgraph/src/file/mod.rs+0−2

@@ -2,12 +2,10 @@ · 1 unmodified line
2	2
3	3	mod access;
4	4
5		−///
6	5	pub mod commit;
7	6	pub use commit::Commit;
8	7
9	8	mod init;
10		−///
11	9	pub mod verify;
12	10
13	11	pub use init::Error;

git-commitgraph/src/file/verify.rs+5−4

@@ -1,3 +1,4 @@
	1	+//! Auxiliary types used in commit graph file verification methods.
1	2	use crate::{
2	3	file::{self, File},
3	4	GENERATION_NUMBER_INFINITY, GENERATION_NUMBER_MAX,
@@ -42,15 +43,15 @@ pub enum Error<E: std::error::Error + 'static> { · 38 unmodified lines
42	43	#[derive(Clone, Debug, Eq, PartialEq)]
43	44	#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
44	45	pub struct Outcome {
45		− /// The highest encountered [`file::Commit`] generation number.
	46	+ /// The largest encountered [`file::Commit`] generation number.
46	47	pub max_generation: u32,
47	48	/// The smallest encountered [`file::Commit`] generation number.
48	49	pub min_generation: u32,
49		− /// The highest amount parents in a single [`file::Commit`].
	50	+ /// The largest number of parents in a single [`file::Commit`].
50	51	pub max_parents: u32,
51		− /// The total amount of [`commits`][file::Commit] seen in the iteration.
	52	+ /// The total number of [`commits`][file::Commit]s seen in the iteration.
52	53	pub num_commits: u32,
53		− /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.
	54	+ /// A mapping of `N -> number of commits with N parents`.
54	55	pub parent_counts: HashMap<u32, u32>,
55	56	}
56	57

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

@@ -45,7 +45,7 @@ impl Graph { · 44 unmodified lines
45	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	49	pub fn num_commits(&self) -> u32 {
50	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	1	//! Operations on a complete commit graph.
2	2	mod access;
3	3	mod init;
4		−///
5	4	pub mod verify;
6	5
7	6	use crate::file::File;

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

@@ -1,3 +1,4 @@
	1	+//! Auxiliary types used by graph verification methods.
1	2	use crate::{
2	3	file::{self, commit},
3	4	graph, Graph, GENERATION_NUMBER_MAX,
@@ -50,17 +51,19 @@ pub enum Error<E: std::error::Error + 'static> { · 46 unmodified lines
50	51	TooManyFiles(usize),
51	52	}
52	53
53		−/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()]`.
	54	+/// Statistics gathered while verifying the integrity of the graph as returned by [`Graph::verify_integrity()`].
54	55	#[derive(Clone, Debug, Eq, PartialEq)]
55	56	#[cfg_attr(feature = "serde1", derive(serde::Deserialize, serde::Serialize))]
56	57	pub struct Outcome {
57		− /// The longest consecutive amount of commits in a chain of commits.
	58	+ /// The length of the longest path between any two commits in this graph.
58	59	///
59		− /// For example, a repository with 10 commits would have 10 as value.
	60	+ /// For example, this will be `Some(9)` for a commit graph containing 10 linear commits.
	61	+ /// This will be `Some(0)` for a commit graph containing 0 or 1 commits.
	62	+ /// If the longest path length is too large to fit in a [u32], then this will be [None].
60	63	pub longest_path_length: Option<u32>,
61		− /// The total amount traversed commits.
	64	+ /// The total number of commits traversed.
62	65	pub num_commits: u32,
63		− /// A mapping of `parent-count -> amount of [commits][file::Commit] with that count`.
	66	+ /// A mapping of `N -> number of commits with N parents`.
64	67	pub parent_counts: BTreeMap<u32, u32>,
65	68	}
66	69

git-commitgraph/src/lib.rs+11−6

@@ -1,11 +1,12 @@
1	1	//! Read, verify, and traverse git commit graphs.
2	2	//!
3		−//! A [commit graph][Graph] acts as a cache is a set of [graph files][file::File] each storing
4		−//! various commits in a way that accelerates lookups considerably compared to traversing the git history by usual means.
	3	+//! A [commit graph][Graph] is an index of commits in the git commit history.
	4	+//! The [Graph] stores commit data in a way that accelerates lookups considerably compared to
	5	+//! traversing the git history by usual means.
5	6	//!
6		−//! A [`Graph`] is generated as each [`File`][file::File] only contains a subset of all commits in the git commit
7		−//! history to avoid having to recreate the entire cache each time the cache should be updated, thus avoiding to traverse
8		−//! the git history that is already present in the [`Graph`].
	7	+//! As generating the full commit graph from scratch can take some time, git may write new commits
	8	+//! to separate [files][file::File] instead of overwriting the original file.
	9	+//! Eventually, git will merge these files together as the number of files grows.
9	10	#![forbid(unsafe_code)]
10	11	#![deny(rust_2018_idioms, missing_docs)]
11	12
@@ -16,7 +17,11 @@ pub use graph::Graph; · 4 unmodified lines
16	17
17	18	/// The number of generations that are considered 'infinite' commit history.
18	19	pub const GENERATION_NUMBER_INFINITY: u32 = 0xffff_ffff;
19		−/// The biggest possible amount of commits in the history of a repository.
	20	+/// The largest valid generation number.
	21	+///
	22	+/// If a commit's real generation number is larger than this, the commit graph will cap the value to
	23	+/// this number.
	24	+/// The largest distinct generation number is `GENERATION_NUMBER_MAX - 1`.
20	25	pub const GENERATION_NUMBER_MAX: u32 = 0x3fff_ffff;
21	26
22	27	/// The maximum number of commits that can be stored in a commit graph.