[object #177] fix docs

Author: Byron

git-object/src/commit.rs

@@ -3,7 +3,7 @@ use bstr::{BStr, ByteSlice};
 pub use crate::immutable::commit::iter::RefIter;
 use crate::{immutable, TagRef};
 
-/// An iterator over extra headers in [owned][crate::mutable::Commit] and [borrowed][crate::CommitRef] commits.
+/// An iterator over extra headers in [owned][crate::Commit] and [borrowed][crate::CommitRef] commits.
 pub struct ExtraHeaders<I> {
     inner: I,
 }

git-object/src/lib.rs

@@ -1,5 +1,5 @@
 //! This crate provides types for [read-only git objects][crate::ObjectRef] backed by bytes provided in git's serialization format
-//! as well as [mutable versions][mutable::Object] of these. The latter can be serialized into git's serialization format for objects.
+//! as well as [mutable versions][Object] of these. The latter can be serialized into git's serialization format for objects.
 #![forbid(unsafe_code)]
 #![deny(rust_2018_idioms, missing_docs)]
 
@@ -37,6 +37,14 @@ pub struct BlobRef<'a> {
     pub data: &'a [u8],
 }
 
+/// A mutable chunk of any [`data`][Blob::data].
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+pub struct Blob {
+    /// The data itself.
+    pub data: Vec<u8>,
+}
+
 /// A git commit parsed using [`from_bytes()`][CommitRef::from_bytes()].
 ///
 /// A commit encapsulates information about a point in time at which the state of the repository is recorded, usually after a
@@ -66,6 +74,30 @@ pub struct CommitRef<'a> {
     pub extra_headers: Vec<(&'a BStr, Cow<'a, BStr>)>,
 }
 
+/// A mutable git commit, representing an annotated state of a working tree along with a reference to its historical commits.
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+pub struct Commit {
+    /// The hash of recorded working tree state.
+    pub tree: git_hash::ObjectId,
+    /// Hash of each parent commit. Empty for the first commit in repository.
+    pub parents: SmallVec<[git_hash::ObjectId; 1]>,
+    /// Who wrote this commit.
+    pub author: git_actor::Signature,
+    /// Who committed this commit.
+    ///
+    /// This may be different from the `author` in case the author couldn't write to the repository themselves and
+    /// is commonly encountered with contributed commits.
+    pub committer: git_actor::Signature,
+    /// The name of the message encoding, otherwise [UTF-8 should be assumed](https://github.com/git/git/blob/e67fbf927dfdf13d0b21dc6ea15dc3c7ef448ea0/commit.c#L1493:L1493).
+    pub encoding: Option<BString>,
+    /// The commit message documenting the change.
+    pub message: BString,
+    /// Extra header fields, in order of them being encountered, made accessible with the iterator returned
+    /// by [`extra_headers()`][Commit::extra_headers()].
+    pub extra_headers: Vec<(BString, BString)>,
+}
+
 /// Represents a git tag, commonly indicating a software release.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
@@ -85,6 +117,24 @@ pub struct TagRef<'a> {
     pub pgp_signature: Option<&'a BStr>,
 }
 
+/// A mutable git tag.
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+pub struct Tag {
+    /// The hash this tag is pointing to.
+    pub target: git_hash::ObjectId,
+    /// The kind of object this tag is pointing to.
+    pub target_kind: crate::Kind,
+    /// The name of the tag, e.g. "v1.0".
+    pub name: BString,
+    /// The message describing the tag.
+    pub message: BString,
+    /// The tags author.
+    pub signature: Option<git_actor::Signature>,
+    /// A pgp signature over all bytes of the encoded tag, excluding the pgp signature itself.
+    pub pgp_signature: Option<BString>,
+}
+
 /// An signature_ref object representing [`Trees`][TreeRef], [`Blobs`][BlobRef], [`Commits`][CommitRef], or [`Tags`][TagRef].
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
@@ -97,6 +147,16 @@ pub enum ObjectRef<'a> {
     Tag(TagRef<'a>),
 }
 
+/// A mutable object representing [`Trees`][Tree], [`Blobs`][Blob], [`Commits`][Commit] or [`Tags`][Tag].
+#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
+#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
+#[allow(clippy::large_enum_variant, missing_docs)]
+pub enum Object {
+    Tree(Tree),
+    Blob(Blob),
+    Commit(Commit),
+    Tag(Tag),
+}
 /// 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))]
@@ -115,71 +175,10 @@ pub struct TreeRefIter<'a> {
     data: &'a [u8],
 }
 
-/// A mutable git tag.
-#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
-#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
-pub struct Tag {
-    /// The hash this tag is pointing to.
-    pub target: git_hash::ObjectId,
-    /// The kind of object this tag is pointing to.
-    pub target_kind: crate::Kind,
-    /// The name of the tag, e.g. "v1.0".
-    pub name: BString,
-    /// The message describing the tag.
-    pub message: BString,
-    /// The tags author.
-    pub signature: Option<git_actor::Signature>,
-    /// A pgp signature over all bytes of the encoded tag, excluding the pgp signature itself.
-    pub pgp_signature: Option<BString>,
-}
-
 /// A mutable Tree, containing other trees, blobs or commits.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Tree {
     /// The directories and files contained in this tree. They must be and remain sorted by [`filename`][Entry::filename].
     pub entries: Vec<Entry>,
 }
-
-/// A mutable git commit, representing an annotated state of a working tree along with a reference to its historical commits.
-#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
-#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
-pub struct Commit {
-    /// The hash of recorded working tree state.
-    pub tree: git_hash::ObjectId,
-    /// Hash of each parent commit. Empty for the first commit in repository.
-    pub parents: SmallVec<[git_hash::ObjectId; 1]>,
-    /// Who wrote this commit.
-    pub author: git_actor::Signature,
-    /// Who committed this commit.
-    ///
-    /// This may be different from the `author` in case the author couldn't write to the repository themselves and
-    /// is commonly encountered with contributed commits.
-    pub committer: git_actor::Signature,
-    /// The name of the message encoding, otherwise [UTF-8 should be assumed](https://github.com/git/git/blob/e67fbf927dfdf13d0b21dc6ea15dc3c7ef448ea0/commit.c#L1493:L1493).
-    pub encoding: Option<BString>,
-    /// The commit message documenting the change.
-    pub message: BString,
-    /// Extra header fields, in order of them being encountered, made accessible with the iterator returned
-    /// by [`extra_headers()`][Commit::extra_headers()].
-    pub extra_headers: Vec<(BString, BString)>,
-}
-
-/// A mutable chunk of any [`data`][Blob::data].
-#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
-#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
-pub struct Blob {
-    /// The data itself.
-    pub data: Vec<u8>,
-}
-
-/// A mutable object representing [`Trees`][Tree], [`Blobs`][Blob], [`Commits`][Commit] or [`Tags`][Tag].
-#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
-#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
-#[allow(clippy::large_enum_variant, missing_docs)]
-pub enum Object {
-    Tree(Tree),
-    Blob(Blob),
-    Commit(Commit),
-    Tag(Tag),
-}

git-object/src/mutable/mod.rs

@@ -1,7 +1,7 @@
 //! Mutable objects with each field being separately allocated and changeable.
 //!
 //! Mutable objects are Commits, Trees, Blobs and Tags that can be changed and serialized.
-//! They either created using object [construction][Object] or by [deserializing existing objects][crate::ObjectRef::from_bytes()]
+//! They either created using object [construction][crate::Object] or by [deserializing existing objects][crate::ObjectRef::from_bytes()]
 //! and converting these [into mutable copies][crate::ObjectRef::into_mutable()] for adjustments.
 
 pub(crate) const NL: &[u8; 1] = b"\n";

git-object/src/tree/mod.rs

@@ -5,7 +5,7 @@ use crate::{bstr::BStr, tree};
 
 /// The mode of items storable in a tree, similar to the file mode on a unix file system.
 ///
-/// Used in [mutable::Entry][crate::mutable::tree::Entry] and [EntryRef].
+/// Used in [mutable::Entry][crate::tree::Entry] and [EntryRef].
 #[derive(Clone, Copy, PartialEq, Eq, Debug, Ord, PartialOrd, Hash)]
 #[repr(u16)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
@@ -30,7 +30,7 @@ impl EntryMode {
     }
 }
 
-/// An element of a [`TreeRef`][TreeRef::entries].
+/// An element of a [`TreeRef`][crate::TreeRef::entries].
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct EntryRef<'a> {
@@ -47,7 +47,7 @@ pub struct EntryRef<'a> {
 
 mod ref_iter;
 
-/// An entry in a [`Tree`], similar to an entry in a directory.
+/// An entry in a [`Tree`][crate::Tree], similar to an entry in a directory.
 #[derive(PartialEq, Eq, Debug, Hash, Clone)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Entry {

git-pack/src/data/object.rs

@@ -25,7 +25,7 @@ impl<'a> Object<'a> {
     /// Decodes the data in the backing slice into a [`git_object::ObjectRef`], allowing to access all of its data
     /// conveniently. The cost of parsing an object is negligible.
     ///
-    /// **Note** that [mutable, decoded objects][git_object::mutable::Object] can be created from a [`crate::data::Object`]
+    /// **Note** that [mutable, decoded objects][git_object::Object] can be created from a [`crate::data::Object`]
     /// using [`git_object::ObjectRef::into_mutable()`].
     pub fn decode(&self) -> Result<ObjectRef<'a>, immutable::object::decode::Error> {
         Ok(match self.kind {