minor improvements to module layout, docs (#266)

experiments/object-access/src/main.rs

@@ -503,6 +503,7 @@ where
 {
     use git_repository::prelude::FindExt;
     let bytes = std::sync::atomic::AtomicU64::default();
+    #[allow(deprecated)]
     let odb = Arc::new(git_repository::odb::linked::Store::at(objects_dir)?);
 
     git_repository::parallel::in_parallel(

git-odb/src/find.rs

@@ -17,7 +17,7 @@ pub mod existing {
 pub mod existing_object {
     use git_hash::ObjectId;
 
-    /// The error returned by the various [`find_*`][crate::FindExt::find_commit()] trait methods.
+    /// The error returned by the various [`find_*()`][crate::FindExt::find_commit()] trait methods.
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error<T: std::error::Error + 'static> {
@@ -36,7 +36,7 @@ pub mod existing_object {
 pub mod existing_iter {
     use git_hash::ObjectId;
 
-    /// The error returned by the various [`find_*`][crate::FindExt::find_commit()] trait methods.
+    /// The error returned by the various [`find_*_iter()`][crate::FindExt::find_commit_iter()] trait methods.
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error<T: std::error::Error + 'static> {
@@ -48,18 +48,3 @@ pub mod existing_iter {
         ObjectKind { expected: git_object::Kind },
     }
 }
-
-/// An Entry in a pack providing access to its data.
-///
-/// Its commonly retrieved by reading from a pack index file followed by a read from a pack data file.
-#[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
-#[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
-#[allow(missing_docs)]
-pub struct Entry<'a> {
-    /// The pack-data encoded bytes of the pack data entry as present in the pack file, including the header followed by compressed data.
-    pub data: &'a [u8],
-    /// The crc32 hash over the entirety of `data`, or None if the pack file format doesn't support it yet.
-    pub crc32: Option<u32>,
-    /// The version of the pack file containing `data`
-    pub version: crate::pack::data::Version,
-}

git-odb/src/lib.rs

@@ -1,20 +1,15 @@
 #![deny(missing_docs, unsafe_code, rust_2018_idioms)]
 
-//! Git stores all of its data as _Objects_, which ata along with a hash over all data. Thus it's an
-//! object store indexed by data with inherent deduplication: the same data will have the same hash, and thus occupy the same
-//! space within the store.
+//! Git stores all of its data as _Objects_, which are data along with a hash over all data. Thus it's an
+//! object store indexed by the signature of data itself with inherent deduplication: the same data will have the same hash,
+//! and thus occupy the same space within the store.
 //!
-//! There are various flavours of object stores, all of which supporting iteration, reading and possibly writing.
+//! There is only one all-round object store, also known as the [`Store`], as it supports ~~everything~~ most of what git has to offer.
 //!
-//! * [`loose::Store`]
-//!   * A database storing one object per file, named by its hash, using zlib compression.
-//!   * O(1) reads and writes, bound by IO operations per second
-//! * [`compound::Store`]
-//!   * A database using a [`loose::Store`] for writes and multiple [`pack::Bundle`]s for object reading. It can also refer to multiple
-//!     additional [`compound::Store`] instances using git-alternates.
-//!   * This is the database closely resembling the object database in a git repository, and probably what most people would want to use.
-//! * [`linked::Store`]
-//!   * A database containing various [`compound::Stores`][compound::Store] as gathered from `alternates` files.
+//! * loose object reading and writing
+//! * access to packed objects
+//! * multiple loose objects and pack locations as gathered from `alternates` files.
+#![allow(deprecated)] // TODO: actually remove the deprecated items and remove thos allow
 use std::path::PathBuf;
 use std::sync::Arc;
 
@@ -28,13 +23,13 @@ pub mod alternate;
 
 /// A thread-local handle to access any object.
 pub type Handle = Cache<general::Handle<OwnShared<general::Store>>>;
-/// A thread-local handle to access any object, but thread-safe and independent of the actual type of OwnShared.
+/// A thread-local handle to access any object, but thread-safe and independent of the actual type of `OwnShared` or feature toggles in `git-features`.
 pub type HandleArc = Cache<general::Handle<Arc<general::Store>>>;
 
 /// A thread-safe store for creation of handles.
 pub type Store = general::Store;
 
-/// Create a new cached odb handle.
+/// Create a new cached odb handle with support for additional options.
 pub fn at_opts(objects_dir: impl Into<PathBuf>, slots: general::init::Slots) -> std::io::Result<Handle> {
     let handle =
         OwnShared::new(general::Store::at_opts(objects_dir, slots)?).to_handle(RefreshMode::AfterAllIndicesLoaded);

git-odb/src/store/compound/mod.rs

@@ -7,8 +7,10 @@ pub mod find;
 pub mod init;
 mod write;
 
-/// An object database with tiered lookup packs and loose objects.
+/// A static object database with tiered lookup in packs and loose objects.
 /// This is a typical git database as used in git repositories, sans 'alternates'.
+/// Note that this ODB won't detect changes on disk and will eagerly map all relevant files. Multipack indices are not supported either.
+#[deprecated(since = "0.27", note = "superseded by git_odb::Store")]
 pub struct Store {
     /// A loose object database into which new objects are written
     pub loose: loose::Store,

git-odb/src/store/linked/mod.rs

@@ -6,6 +6,7 @@ use crate::store::compound;
 /// It does not contain any objects itself.
 ///
 /// Furthermore, it won't handle multi-pack indices and might be removed at some point in the future to allow focussing on a single database.
+#[deprecated(since = "0.27", note = "superseded by git_odb::Store")]
 pub struct Store {
     /// The compound databases containing the actual objects.
     pub dbs: Vec<compound::Store>,