feat: Minor cleanup of docs and trait defs. (#112)

This commit marks the contents of the HashAlgorithm and ObjectType
traits as hidden, because their internals are _only_ relevant to the
internals of `GitOid`. The trait is sealed, so it can't be implemented
by other types, and the types that _do_ implement it aren't able to be
constructed (no public constructor + private field).

This also moves all exported items to the top level, so there are no
public submodules. The API of the crate is quite small, so it's nice
for users to have all the docs accessible from one place.

Signed-off-by: Andrew Lilley Brinker <[email protected]>

gitoid/src/hash_algorithm.rs

@@ -13,30 +13,33 @@ use generic_array::GenericArray;
 /// Hash algorithms that can be used to make a [`GitOid`].
 ///
 /// This is a sealed trait to ensure it's only used for hash
-/// algorithms which are actually supported by Git. No other
-/// types, even if they implement [`Digest`] can implement
-/// this trait.
+/// algorithms which are actually supported by Git.
 ///
 /// For more information on sealed traits, read Predrag
 /// Gruevski's ["A Definitive Guide to Sealed Traits in Rust"][1].
 ///
 /// [1]: https://predr.ag/blog/definitive-guide-to-sealed-traits-in-rust/
 pub trait HashAlgorithm: Sealed {
     /// The name of the hash algorithm in lowercase ASCII.
+    #[doc(hidden)]
     const NAME: &'static str;
 
     /// The actual digest type used by the algorithm.
+    #[doc(hidden)]
     type Alg: Digest;
 
     /// The array type generated by the hash.
+    #[doc(hidden)]
     type Array: Copy + PartialEq + Ord + Hash + Debug + Deref<Target = [u8]>;
 
     /// Helper function to convert the GenericArray type to Self::Array
+    #[doc(hidden)]
     fn array_from_generic(
         arr: GenericArray<u8, <Self::Alg as OutputSizeUser>::OutputSize>,
     ) -> Self::Array;
 
     /// Get an instance of the digester.
+    #[doc(hidden)]
     fn new() -> Self::Alg;
 }
 

gitoid/src/lib.rs

@@ -87,48 +87,32 @@
 //! ## Using this Crate
 //!
 //! The central type of this crate is [`GitOid`], which is generic over both
-//! the hash algorithm used and the object type being identified. The
-//! [`HashAlgorithm`] trait, which is sealed, is implemented by the types
-//! found in `gitoid::hash`. The [`ObjectType`] trait, which is also sealed,
-//! is implemented by the types found in `gitoid::object`.
+//! the hash algorithm used and the object type being identified. These are
+//! defined by the [`HashAlgorithm`] and [`ObjectType`] traits.
 //!
 //! [gitoid]: https://git-scm.com/book/en/v2/Git-Internals-Git-Objects
 //! [omnibor]: https://omnibor.io
 
+pub(crate) mod sealed;
+
 mod error;
-//pub mod ffi;
 mod gitoid;
 mod hash_algorithm;
 mod object_type;
-pub(crate) mod sealed;
+
 #[cfg(test)]
 mod tests;
 
-pub use crate::error::Error;
 pub(crate) use crate::error::Result;
+
+pub use crate::error::Error;
 pub use crate::gitoid::GitOid;
 pub use crate::hash_algorithm::HashAlgorithm;
+pub use crate::hash_algorithm::Sha1;
+pub use crate::hash_algorithm::Sha1Cd;
+pub use crate::hash_algorithm::Sha256;
+pub use crate::object_type::Blob;
+pub use crate::object_type::Commit;
 pub use crate::object_type::ObjectType;
-
-pub mod object {
-    //! Object types supported for [`GitOid`] construction.
-
-    #[cfg(doc)]
-    use crate::GitOid;
-
-    pub use crate::object_type::Blob;
-    pub use crate::object_type::Commit;
-    pub use crate::object_type::Tag;
-    pub use crate::object_type::Tree;
-}
-
-pub mod hash {
-    //! Hash algorithms supported for [`GitOid`] construction.
-
-    #[cfg(doc)]
-    use crate::GitOid;
-
-    pub use crate::hash_algorithm::Sha1;
-    pub use crate::hash_algorithm::Sha1Cd;
-    pub use crate::hash_algorithm::Sha256;
-}
+pub use crate::object_type::Tag;
+pub use crate::object_type::Tree;

gitoid/src/object_type.rs

@@ -4,8 +4,15 @@ use crate::sealed::Sealed;
 #[cfg(doc)]
 use crate::GitOid;
 
-/// Object types usable to construct a [`GitOid`]
+/// Object types usable to construct a [`GitOid`].
+///
+/// This is a sealed trait to ensure it's only used for hash
+/// algorithms which are actually supported by Git.
+///
+/// For more information on sealed traits, read Predrag
+/// Gruevski's ["A Definitive Guide to Sealed Traits in Rust"][1].
 pub trait ObjectType: Sealed {
+    #[doc(hidden)]
     const NAME: &'static str;
 }
 

gitoid/src/tests.rs

@@ -1,5 +1,3 @@
-use super::hash::*;
-use super::object::*;
 use super::*;
 use std::fs::File;
 use tokio::fs::File as AsyncFile;