more commitgraph docs

Sebastian Thiel committed 5 years ago

Commit a81ea671 parent cba048f4 files · +26 −3Browse files

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

Unified · Split

3 files

git-commitgraph/src/graph/access.rs +11 −0
git-commitgraph/src/graph/init.rs +8 −0
git-commitgraph/src/graph/verify.rs +2 −0

git-commitgraph/src/graph/access.rs+11−0

 /// Access
 impl Graph {
+    /// Returns the commit at the given position `pos`.
+    ///
+    /// # Panics
+    /// If `pos` is greater or equal to [`num_commits()`][Graph::num_commits()].
     pub fn commit_at(&self, pos: graph::Position) -> Commit<'_> {
         let r = self.lookup_by_pos(pos);
         r.file.commit_at(r.pos)
     }
+    /// Returns the commit matching the given `id`.
     pub fn commit_by_id(&self, id: borrowed::Id<'_>) -> Option<Commit<'_>> {
         let r = self.lookup_by_id(id)?;
         Some(r.file.commit_at(r.file_pos))
     }
+    /// Returns the `hash` at the given position `pos`.
+    ///
+    /// # Panics
+    /// If `pos` is greater or equal to [`num_commits()`][Graph::num_commits()].
     pub fn id_at(&self, pos: graph::Position) -> borrowed::Id<'_> {
         let r = self.lookup_by_pos(pos);
         r.file.id_at(r.pos)
         self.files.iter().flat_map(|file| file.iter_ids())
     }
+    /// Translate the given `id` to its position in the file.
     pub fn lookup(&self, id: borrowed::Id<'_>) -> Option<graph::Position> {
         Some(self.lookup_by_id(id)?.graph_pos)
     }
+    /// Returns the amount of commits stored in this file.
     pub fn num_commits(&self) -> u32 {
         self.files.iter().map(|f| f.num_commits()).sum()
     }

git-commitgraph/src/graph/init.rs+8−0

     path::{Path, PathBuf},
 };
+/// The error used in the [`graph`][crate::graph] module.
 #[derive(thiserror::Error, Debug)]
+#[allow(missing_docs)]
 pub enum Error {
     #[error("{}", .path.display())]
     File {
 /// Instantiate a `Graph` from various sources.
 impl Graph {
+    /// Instantiate a commit graph from `path` which may be a directory containing graph files or the graph file itself.
     pub fn at(path: impl AsRef<Path>) -> Result<Self, Error> {
         Self::try_from(path.as_ref())
     }
+    /// Instantiate a commit graph from the directory containing all of its files.
     pub fn from_commit_graphs_dir(path: impl AsRef<Path>) -> Result<Self, Error> {
         let commit_graphs_dir = path.as_ref();
         let chain_file_path = commit_graphs_dir.join("commit-graph-chain");
         Self::new(files)
     }
+    /// Instantiate a commit graph from a `.git/objects/info/commit-graph` or
+    /// `.git/objects/info/commit-graphs/graph-*.graph` file.
     pub fn from_file(path: impl AsRef<Path>) -> Result<Self, Error> {
         let path = path.as_ref();
         let file = File::at(path).map_err(|e| Error::File {
         Self::new(vec![file])
     }
+    /// Instantiate a commit graph from an `.git/objects/info` directory.
     pub fn from_info_dir(info_dir: impl AsRef<Path>) -> Result<Self, Error> {
         Self::from_file(info_dir.as_ref().join("commit-graph"))
             .or_else(|_| Self::from_commit_graphs_dir(info_dir.as_ref().join("commit-graphs")))
     }
+    /// Create a new commit graph from a list of `files`.
     pub fn new(files: Vec<File>) -> Result<Self, Error> {
         let num_commits: u64 = files.iter().map(|f| u64::from(f.num_commits())).sum();
         if num_commits > u64::from(MAX_COMMITS) {

git-commitgraph/src/graph/verify.rs+2−0

     path::PathBuf,
 };
+/// The error used in [`verify_integrity()`][Graph::verify_integrity].
 #[derive(thiserror::Error, Debug)]
+#[allow(missing_docs)]
 pub enum Error<E: std::error::Error + 'static> {
     #[error("'{}' should have {expected} base graphs, but claims {actual} base graphs", .path.display())]
     BaseGraphCount { actual: u8, expected: u8, path: PathBuf },

more commitgraph docs

Keyboard shortcuts

General

Issues and pull requests

Issues, pull requests and Inbox

Repository code