first round of git-object doc proof reading

Author: Byron

git-object/src/borrowed/blob.rs

@@ -9,7 +9,7 @@ pub struct Blob<'a> {
 }
 
 impl<'a> Blob<'a> {
-    /// Instantiate a `Blob` from the given `data`
+    /// Instantiate a `Blob` from the given `data`, which is used as-is.
     pub fn from_bytes(data: &[u8]) -> Result<Blob<'_>, Infallible> {
         Ok(Blob { data })
     }

git-object/src/borrowed/commit.rs

@@ -13,7 +13,7 @@ use nom::{
 use smallvec::SmallVec;
 use std::borrow::Cow;
 
-/// A shared git commit, created using [`from_bytes()`][Commit::from_bytes()].
+/// A git commit parsed using [`from_bytes()`][Commit::from_bytes()].
 ///
 /// A commit encapsulates information about a point in time at which the state of the repository is recorded, usually after a
 /// change which is documented in the commit `message`.
@@ -47,7 +47,7 @@ impl<'a> Commit<'a> {
     pub fn from_bytes(data: &'a [u8]) -> Result<Commit<'a>, Error> {
         parse(data).map(|(_, t)| t).map_err(Error::from)
     }
-    /// Return the `tree` fields hash.
+    /// Return the `tree` fields hash digest.
     pub fn tree(&self) -> owned::Id {
         owned::Id::from_40_bytes_in_hex(self.tree).expect("prior validation")
     }

git-object/src/borrowed/id.rs

@@ -3,7 +3,7 @@ use bstr::ByteSlice;
 use std::convert::{TryFrom, TryInto};
 use std::fmt;
 
-/// A borrowed reference to a hash identifying objects
+/// A borrowed reference to a hash identifying objects.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize))]
 pub struct Id<'a>(&'a [u8; SHA1_SIZE]);

git-object/src/borrowed/mod.rs

@@ -1,7 +1,7 @@
-//! Borrowed objects are read-only structures referencing most data in a byte based backing store.
+//! Borrowed objects are read-only structures referencing most data from a byte slice.
 //!
 //! Borrowed objects are expected to be deserialized from bytes that acts as backing store, and they
-//! cannot mutated or serialized. Instead, one will convert them into their `owned` counterparts,
+//! cannot be mutated or serialized. Instead, one will convert them into their [`owned`][crate::owned] counterparts
 //! which support mutation and serialization.
 mod commit;
 pub use commit::Commit;

git-object/src/borrowed/tree.rs

@@ -10,7 +10,7 @@ use nom::{
 };
 use std::convert::TryFrom;
 
-/// A directory recording contained files (blobs), directories (trees) and submodules (commits).
+/// A directory snapshot containing files (blobs), directories (trees) and submodules (commits).
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Tree<'a> {

git-object/src/lib.rs

@@ -1,5 +1,5 @@
-//! This crate provides types for [read-only git objects][borrowed::Object] backed by bytes provided in gits serialization format
-//! as well as [mutable versions][owned::Object] of these. The latter can be serialized into gits serialization format for objects.
+//! This crate provides types for [read-only git objects][borrowed::Object] backed by bytes provided in git's serialization format
+//! as well as [mutable versions][owned::Object] of these. The latter can be serialized into git's serialization format for objects.
 #![forbid(unsafe_code)]
 #![deny(rust_2018_idioms, missing_docs)]
 
@@ -8,13 +8,11 @@ use bstr::{BStr, BString, ByteSlice};
 /// For convenience to allow using `bstr` without adding it to own cargo manifest
 pub use bstr;
 
-/// Objects sharing data with a backing store to minimize allocations
 pub mod borrowed;
-/// Mutable objects with each field being separately allocated and mutable.
 pub mod owned;
 
 mod types;
-pub use types::*;
+pub use types::{tree, Error, Kind, Sign, Time, SHA1_SIZE};
 
 ///
 pub mod commit;

git-object/src/owned/mod.rs

@@ -1,3 +1,5 @@
+//! Mutable objects with each field being separately allocated and mutable.
+//!
 //! Owned objects are Commits, Trees, Blobs and Tags that can be mutated and serialized.
 
 pub(crate) const NL: &[u8; 1] = b"\n";

git-object/src/types.rs

@@ -2,7 +2,7 @@ use crate::owned::SPACE;
 use quick_error::quick_error;
 use std::{fmt, io};
 
-/// Indicates if a number is positive or negative
+/// Indicates if a number is positive or negative for use in [`Time`].
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 #[allow(missing_docs)]
@@ -56,7 +56,7 @@ impl Time {
 /// The size of a SHA1 hash digest in bytes
 pub const SHA1_SIZE: usize = 20;
 
-/// The four types of objects that git differentiates
+/// The four types of objects that git differentiates.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 #[allow(missing_docs)]

tasks.md

@@ -3,6 +3,9 @@
 * **git-odb**
   * [x] all docs, sans examples
   * [x] Rename pack data/pack index `Kind` to `Version` or similar, because that's what it really is.
+* **git-object** refactor     
+  * [ ] split `Id` and everything hash related into `git-id`
+  * [ ] use `git-id` inside of `git-features`, remove cycle
 * **Documentation (with deny(missing_docs))**
   * [x] git-features
   * [ ] git-object