document loose::Object entirely

Byron · Byron · commit d5eef9cdd069 · 2020-10-10T18:49:20.000+08:00
diff --git a/git-odb/src/loose/mod.rs b/git-odb/src/loose/mod.rs
@@ -1,3 +1,4 @@
+//! An object database storing each object in a zlib compressed file with its hash in the path
 const HEADER_READ_COMPRESSED_BYTES: usize = 256;
 const HEADER_READ_UNCOMPRESSED_BYTES: usize = 512;
 
diff --git a/git-odb/src/loose/object/decode.rs b/git-odb/src/loose/object/decode.rs
@@ -20,15 +20,25 @@ pub enum Error {
     },
 }
 
+// Decoding and streaming
 impl loose::Object {
-    /// **Note**: Blobs are loaded into memory and are made available that way.
+    /// Decode the object to make it's fields accessible in case of Trees, Tags and Commits.
+    ///
+    /// This is a zero-copy operation with data read from disk if needed and stored in memory.
+    /// The returned [`borrowed::Object`] references this data where possible.
+    ///
+    /// **Note**: Blobs are also loaded into memory and are made available that way.
     /// Consider using `stream()` if large Blobs are expected.
     pub fn decode(&mut self) -> Result<borrowed::Object<'_>, Error> {
         self.decompress_all()?;
         let bytes = &self.decompressed_data[self.header_size..];
         Ok(borrowed::Object::from_bytes(self.kind, bytes)?)
     }
 
+    /// Returns an implementation of [`std::io::Read`], which decompresses the objects data on the fly.
+    ///
+    /// **Note**: This is most useful for big blobs as these won't be read into memory in full. Use [`decode()`][loose::Object::decode()] for
+    /// Trees, Tags and Commits instead for convenient access to their payload.
     pub fn stream(&mut self) -> Result<stream::Reader<'_>, Error> {
         match &self.path {
             Some(path) => Ok(stream::Reader::from_read(
diff --git a/git-odb/src/loose/object/header.rs b/git-odb/src/loose/object/header.rs
@@ -1,3 +1,4 @@
+//! loose object header encoding and decoding
 use byteorder::WriteBytesExt;
 use git_object as object;
 
@@ -15,6 +16,9 @@ pub enum Error {
     ObjectHeader(#[from] object::Error),
 }
 
+/// Decode a loose object header, being `<kind> <size>\0`, returns ([`Kind`][object::Kind], `size`, `consumed bytes`).
+///
+/// `size` is the uncompressed size of the payload in bytes.
 pub fn decode(input: &[u8]) -> Result<(object::Kind, u64, usize), Error> {
     let header_end = input
         .iter()
@@ -46,6 +50,7 @@ fn kind_to_bytes_with_space(object: object::Kind) -> &'static [u8] {
     }
 }
 
+/// Encode the objects `Kind` and `size` into a format suitable for use with [`decode()`].
 pub fn encode(object: object::Kind, size: u64, mut out: impl std::io::Write) -> Result<usize, std::io::Error> {
     let mut written = out.write(kind_to_bytes_with_space(object))?;
     written += itoa::write(&mut out, size)?;
diff --git a/git-odb/src/loose/object/mod.rs b/git-odb/src/loose/object/mod.rs
@@ -3,9 +3,12 @@ use git_object as object;
 use smallvec::SmallVec;
 use std::path::PathBuf;
 
+/// A representation of a loose object on disk, which is fully or partially read into memory
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 pub struct Object {
+    /// The kind of object
     pub kind: object::Kind,
+    /// The uncompressed size of the object's data/payload
     pub size: usize,
     pub(crate) decompressed_data: SmallVec<[u8; HEADER_READ_UNCOMPRESSED_BYTES]>,
     pub(crate) compressed_data: SmallVec<[u8; HEADER_READ_COMPRESSED_BYTES]>,
diff --git a/git-odb/src/loose/object/stream.rs b/git-odb/src/loose/object/stream.rs
@@ -6,6 +6,7 @@ pub enum Reader<'a> {
     Buffer(&'a [u8]),
 }
 
+/// A [`Read`][std::io::Read] implementation for reading from a file or from borrowed data.
 impl<'a> Reader<'a> {
     pub fn from_read(header_size: usize, file: std::fs::File) -> Reader<'a> {
         Reader::File(header_size, InflateReader::from_read(std::io::BufReader::new(file)))
diff --git a/git-odb/src/loose/object/verify.rs b/git-odb/src/loose/object/verify.rs
@@ -13,6 +13,9 @@ pub enum Error {
 }
 
 impl loose::Object {
+    /// Generate the git hash of this object, reading it in the process, and compare it with the given `desired` [Id][borrowed::Id].
+    ///
+    /// Returns an error with the actual id if the hashes don't match.
     pub fn verify_checksum(&mut self, desired: borrowed::Id<'_>) -> Result<(), Error> {
         let mut sink = HashWrite::new(io::sink(), desired.kind());
         let (kind, size) = (self.kind, self.size);

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+//! An object database storing each object in a zlib compressed file with its hash in the path`
`1`	`2`	`const HEADER_READ_COMPRESSED_BYTES: usize = 256;`
`2`	`3`	`const HEADER_READ_UNCOMPRESSED_BYTES: usize = 512;`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+//! loose object header encoding and decoding`
`1`	`2`	`use byteorder::WriteBytesExt;`
`2`	`3`	`use git_object as object;`
`3`	`4`
`@@ -15,6 +16,9 @@ pub enum Error {`
`15`	`16`	`ObjectHeader(#[from] object::Error),`
`16`	`17`	`}`
`17`	`18`
	`19`	+/// Decode a loose object header, being `<kind> <size>\0`, returns ([`Kind`][object::Kind], `size`, `consumed bytes`).
	`20`	`+///`
	`21`	+/// `size` is the uncompressed size of the payload in bytes.
`18`	`22`	`pub fn decode(input: &[u8]) -> Result<(object::Kind, u64, usize), Error> {`
`19`	`23`	`let header_end = input`
`20`	`24`	`.iter()`
`@@ -46,6 +50,7 @@ fn kind_to_bytes_with_space(object: object::Kind) -> &'static [u8] {`
`46`	`50`	`}`
`47`	`51`	`}`
`48`	`52`
	`53`	+/// Encode the objects `Kind` and `size` into a format suitable for use with [`decode()`].
`49`	`54`	`pub fn encode(object: object::Kind, size: u64, mut out: impl std::io::Write) -> Result<usize, std::io::Error> {`
`50`	`55`	`let mut written = out.write(kind_to_bytes_with_space(object))?;`
`51`	`56`	`written += itoa::write(&mut out, size)?;`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@ pub enum Reader<'a> {`
`6`	`6`	`Buffer(&'a [u8]),`
`7`	`7`	`}`
`8`	`8`
	`9`	+/// A [`Read`][std::io::Read] implementation for reading from a file or from borrowed data.
`9`	`10`	`impl<'a> Reader<'a> {`
`10`	`11`	`pub fn from_read(header_size: usize, file: std::fs::File) -> Reader<'a> {`
`11`	`12`	`Reader::File(header_size, InflateReader::from_read(std::io::BufReader::new(file)))`
Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,9 @@ pub enum Error {`
`13`	`13`	`}`
`14`	`14`
`15`	`15`	`impl loose::Object {`
	`16`	+ /// Generate the git hash of this object, reading it in the process, and compare it with the given `desired` [Id][borrowed::Id].
	`17`	`+ ///`
	`18`	`+ /// Returns an error with the actual id if the hashes don't match.`
`16`	`19`	`pub fn verify_checksum(&mut self, desired: borrowed::Id<'_>) -> Result<(), Error> {`
`17`	`20`	`let mut sink = HashWrite::new(io::sink(), desired.kind());`
`18`	`21`	`let (kind, size) = (self.kind, self.size);`