Merge branch 'fix-docs'

Author: Byron

gitoxide-core/src/hours/mod.rs

@@ -31,9 +31,9 @@ pub struct Context<W> {
 /// Estimate the hours it takes to produce the content of the repository in `_working_dir_`, with `_refname_` for
 /// the start of the commit graph traversal.
 ///
-/// * _working_dir_ - The directory containing a '.git/' folder.
-/// * _refname_ - The name of the ref like 'main' or 'master' at which to start iterating the commit graph.
-/// * _progress_ - A way to provide progress and performance information
+/// * `_working_dir_` - The directory containing a '.git/' folder.
+/// * `_refname_` - The name of the ref like 'main' or 'master' at which to start iterating the commit graph.
+/// * `_progress_` - A way to provide progress and performance information
 pub fn estimate<W, P>(
     working_dir: &Path,
     rev_spec: &BStr,

gix-chunk/src/file/decode.rs

@@ -1,7 +1,7 @@
 use std::{convert::TryInto, ops::Range};
 
 mod error {
-    /// The value returned by [crate::FileRef::from_bytes()
+    /// The value returned by [`crate::file::Index::from_bytes()`]
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix-chunk/src/file/index.rs

@@ -6,7 +6,7 @@ use crate::file::Index;
 pub mod offset_by_kind {
     use std::fmt::{Display, Formatter};
 
-    /// The error returned by [Index::offset_by_kind()][super::Index::offset_by_id()].
+    /// The error returned by [`Index::offset_by_id()`][super::Index::offset_by_id()].
     #[allow(missing_docs)]
     #[derive(Debug)]
     pub struct Error {
@@ -28,7 +28,7 @@ pub mod offset_by_kind {
 
 ///
 pub mod data_by_kind {
-    /// The error returned by [Index::data_by_kind()][super::Index::data_by_id()].
+    /// The error returned by [`Index::data_by_id()`][super::Index::data_by_id()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix-commitgraph/src/file/access.rs

@@ -18,7 +18,7 @@ impl File {
 
     /// Returns the commit data for the commit located at the given lexigraphical position.
     ///
-    /// `pos` must range from 0 to self.num_commits().
+    /// `pos` must range from 0 to `self.num_commits()`.
     ///
     /// # Panics
     ///
@@ -35,7 +35,7 @@ impl File {
     }
 
     /// Returns an object id at the given index in our list of (sorted) hashes.
-    /// The position ranges from 0 to self.num_commits()
+    /// The position ranges from 0 to `self.num_commits()`
     // copied from gix-odb/src/pack/index/ext
     pub fn id_at(&self, pos: file::Position) -> &gix_hash::oid {
         assert!(

gix-config-value/src/types.rs

@@ -24,7 +24,7 @@ pub struct Color {
 /// wish to obtain the true value of the integer, you must account for the
 /// suffix after fetching the value. [`integer::Suffix`] provides
 /// [`bitwise_offset()`][integer::Suffix::bitwise_offset] to help with the
-/// math, or [to_decimal()][Integer::to_decimal()] for obtaining a usable value in one step.
+/// math, or [`to_decimal()`][Integer::to_decimal()] for obtaining a usable value in one step.
 #[derive(Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 pub struct Integer {
     /// The value, without any suffix modification

gix-config/src/file/init/from_paths.rs

@@ -63,7 +63,7 @@ impl File<'static> {
         Self::from_paths_metadata_buf(path_meta, &mut buf, err_on_nonexisting_paths, options)
     }
 
-    /// Like [from_paths_metadata()][Self::from_paths_metadata()], but will use `buf` to temporarily store the config file
+    /// Like [`from_paths_metadata()`][Self::from_paths_metadata()], but will use `buf` to temporarily store the config file
     /// contents for parsing instead of allocating an own buffer.
     ///
     /// If `err_on_nonexisting_paths` is false, instead of aborting with error, we will continue to the next path instead.

gix-config/src/file/section/mod.rs

@@ -52,7 +52,7 @@ impl<'a> Section<'a> {
     }
 
     /// Return the unique `id` of the section, for use with the `*_by_id()` family of methods
-    /// in [gix_config::File][crate::File].
+    /// in [`gix_config::File`][crate::File].
     pub fn id(&self) -> SectionId {
         self.id
     }

gix-diff/src/tree/changes.rs

@@ -8,7 +8,7 @@ use crate::{
     tree::{visit::Change, TreeInfoPair},
 };
 
-/// The error returned by [tree::Changes::needed_to_obtain()].
+/// The error returned by [`tree::Changes::needed_to_obtain()`].
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
 pub enum Error {
@@ -42,7 +42,7 @@ impl<'a> tree::Changes<'a> {
     ///   by the delegate implementation which should be as specific as possible. Rename tracking can be computed on top of the changes
     ///   received by the `delegate`.
     /// * cycle checking is not performed, but can be performed in the delegate which can return [`tree::visit::Action::Cancel`] to stop the traversal.
-    /// * [std::mem::ManuallyDrop] is used because `Peekable` is needed. When using it as wrapper around our no-drop iterators, all of the sudden
+    /// * [`std::mem::ManuallyDrop`] is used because `Peekable` is needed. When using it as wrapper around our no-drop iterators, all of the sudden
     ///   borrowcheck complains as Drop is present (even though it's not)
     ///
     /// [git_cmp_c]: https://github.com/git/git/blob/311531c9de557d25ac087c1637818bd2aad6eb3a/tree-diff.c#L49:L65

gix-diff/src/tree/recorder.rs

@@ -18,7 +18,7 @@ pub enum Location {
 }
 
 /// A Change as observed by a call to [`visit(…)`][visit::Visit::visit()], enhanced with the path affected by the change.
-/// Its similar to [visit::Change] but includes the path that changed.
+/// Its similar to [`visit::Change`] but includes the path that changed.
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[allow(missing_docs)]
 pub enum Change {

gix-discover/src/upwards/types.rs

@@ -1,6 +1,6 @@
 use std::{env, ffi::OsStr, path::PathBuf};
 
-/// The error returned by [gix_discover::upwards()][crate::upwards()].
+/// The error returned by [`gix_discover::upwards()`][crate::upwards()].
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
 pub enum Error {

gix-features/src/parallel/mod.rs

@@ -1,12 +1,12 @@
 //! Run computations in parallel, or not based the `parallel` feature toggle.
 //!
-//! ### in_parallel(…)
+//! ### `in_parallel`(…)
 //!
 //! The [`in_parallel(…)`][in_parallel()] is the typical fan-out-fan-in mode of parallelism, with thread local storage
 //! made available to a `consume(…)` function to process input. The result is sent to the [`Reduce`] running in the calling
 //! thread to aggregate the results into a single output, which is returned by [`in_parallel()`].
 //!
-//! Interruptions can be achieved by letting the reducers [`feed(…)`][Reduce::feed()]` method fail.
+//! Interruptions can be achieved by letting the reducers [`feed(…)`][Reduce::feed()] method fail.
 //!
 //! It gets a boost in usability as it allows threads to borrow variables from the stack, most commonly the repository itself
 //! or the data to work on.

gix-features/src/threading.rs

@@ -17,7 +17,7 @@ mod _impl {
     pub type Mutable<T> = parking_lot::Mutex<T>;
     /// A guarded reference suitable for safekeeping in a struct.
     pub type RefGuard<'a, T> = parking_lot::RwLockReadGuard<'a, T>;
-    /// A mapped reference created from a RefGuard
+    /// A mapped reference created from a `RefGuard`
     pub type MappedRefGuard<'a, U> = parking_lot::MappedRwLockReadGuard<'a, U>;
 
     /// Get a shared reference through a [`MutableOnDemand`] for read-only access.

gix-fs/src/stack.rs

@@ -56,7 +56,7 @@ impl Stack {
     /// Set the current stack to point to the `relative` path and call `push_comp()` each time a new path component is popped
     /// along with the stacks state for inspection to perform an operation that produces some data.
     ///
-    /// The full path to `relative` will be returned along with the data returned by push_comp.
+    /// The full path to `relative` will be returned along with the data returned by `push_comp`.
     /// Note that this only works correctly for the delegate's `push_directory()` and `pop_directory()` methods if
     /// `relative` paths are terminal, so point to their designated file or directory.
     pub fn make_relative_path_current(

gix-glob/src/pattern.rs

@@ -30,7 +30,7 @@ bitflags! {
 
 /// Describes whether to match a path case sensitively or not.
 ///
-/// Used in [Pattern::matches_repo_relative_path()].
+/// Used in [`Pattern::matches_repo_relative_path()`].
 #[derive(Default, Debug, PartialOrd, PartialEq, Copy, Clone, Hash, Ord, Eq)]
 pub enum Case {
     /// The case affects the match

gix-hash/src/oid.rs

@@ -206,7 +206,7 @@ impl PartialEq<crate::ObjectId> for &oid {
 
 /// Manually created from a version that uses a slice, and we forcefully try to convert it into a borrowed array of the desired size
 /// Could be improved by fitting this into serde.
-/// Unfortunately the serde::Deserialize derive wouldn't work for borrowed arrays.
+/// Unfortunately the `serde::Deserialize` derive wouldn't work for borrowed arrays.
 #[cfg(feature = "serde")]
 impl<'de: 'a, 'a> serde::Deserialize<'de> for &'a oid {
     fn deserialize<D>(deserializer: D) -> Result<Self, <D as serde::Deserializer<'de>>::Error>

gix-hash/src/prefix.rs

@@ -2,7 +2,7 @@ use std::{cmp::Ordering, convert::TryFrom};
 
 use crate::{oid, ObjectId, Prefix};
 
-/// The error returned by [Prefix::new()].
+/// The error returned by [`Prefix::new()`].
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
 pub enum Error {
@@ -17,7 +17,7 @@ pub enum Error {
 
 ///
 pub mod from_hex {
-    /// The error returned by [Prefix::from_hex][super::Prefix::from_hex()].
+    /// The error returned by [`Prefix::from_hex`][super::Prefix::from_hex()].
     #[derive(Debug, Eq, PartialEq, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix-hashtable/src/lib.rs

@@ -1,4 +1,4 @@
-//! Customized HashMap and Hasher implementation optimized for using `ObjectId`s as keys.
+//! Customized `HashMap` and Hasher implementation optimized for using `ObjectId`s as keys.
 //!
 //! The crate mirrors `std::collections` in layout for familiarity.
 #![deny(missing_docs, rust_2018_idioms)]
@@ -35,7 +35,7 @@ pub mod sync {
 
 ///
 pub mod hash {
-    /// A Hasher for usage with HashMap keys that are already robust hashes (like an `ObjectId`).
+    /// A Hasher for usage with `HashMap` keys that are already robust hashes (like an `ObjectId`).
     /// The first `8` bytes of the hash are used as the `HashMap` hash
     #[derive(Default, Clone, Copy)]
     pub struct Hasher(u64);
@@ -75,7 +75,7 @@ pub mod hash {
         panic_other_writers!(write_isize, isize);
     }
 
-    /// A Hasher for usage with HashMap keys that are already robust hashes (like an `ObjectId`).
+    /// A Hasher for usage with `HashMap` keys that are already robust hashes (like an `ObjectId`).
     /// The first `8` bytes of the hash are used as the `HashMap` hash
     #[derive(Default, Clone, Copy)]
     pub struct Builder;
@@ -88,9 +88,9 @@ pub mod hash {
     }
 }
 
-/// A HashMap for usage with keys that are already robust hashes (like an `ObjectId`).
+/// A `HashMap` for usage with keys that are already robust hashes (like an `ObjectId`).
 /// The first `8` bytes of the hash are used as the `HashMap` hash
 pub type HashMap<K, V> = hashbrown::HashMap<K, V, hash::Builder>;
-/// A HashSet for usage with keys that are already robust hashes (like an `ObjectId`).
+/// A `HashSet` for usage with keys that are already robust hashes (like an `ObjectId`).
 /// The first `8` bytes of the hash are used as the `HashMap` hash
 pub type HashSet<T = ObjectId> = hashbrown::HashSet<T, hash::Builder>;

gix-index/src/access/mod.rs

@@ -103,14 +103,14 @@ impl State {
 
     /// Return the entry at `idx` or _panic_ if the index is out of bounds.
     ///
-    /// The `idx` is typically returned by [entry_by_path_and_stage()][State::entry_by_path_and_stage()].
+    /// The `idx` is typically returned by [`entry_by_path_and_stage()`][State::entry_by_path_and_stage()].
     pub fn entry(&self, idx: usize) -> &Entry {
         &self.entries[idx]
     }
 
     /// Returns a boolean value indicating whether the index is sparse or not.
     ///
-    /// An index is sparse if it contains at least one [Mode::DIR][entry::Mode::DIR] entry.
+    /// An index is sparse if it contains at least one [`Mode::DIR`][entry::Mode::DIR] entry.
     pub fn is_sparse(&self) -> bool {
         self.is_sparse
     }
@@ -180,7 +180,7 @@ impl State {
     /// [`entry_index_by_path_and_stage_bounded()`][State::entry_index_by_path_and_stage_bounded()] is used with
     /// the `upper_bound` being the amount of entries before the first call to this method.
     ///
-    /// Alternatively, make sure to call [sort_entries()][State::sort_entries()] before entry lookup by path to restore
+    /// Alternatively, make sure to call [`sort_entries()`][State::sort_entries()] before entry lookup by path to restore
     /// the invariant.
     pub fn dangerously_push_entry(
         &mut self,

gix-index/src/decode/mod.rs

@@ -10,7 +10,7 @@ mod error {
 
     use crate::{decode, extension};
 
-    /// The error returned by [State::from_bytes()][crate::State::from_bytes()].
+    /// The error returned by [`State::from_bytes()`][crate::State::from_bytes()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix-index/src/entry/stat.rs

@@ -75,7 +75,7 @@ impl Stat {
         }
     }
 
-    /// Creates stat information from the result of symlink_metadata.
+    /// Creates stat information from the result of `symlink_metadata`.
     pub fn from_fs(fstat: &std::fs::Metadata) -> Result<Stat, SystemTimeError> {
         let mtime = fstat.modified().unwrap_or(std::time::UNIX_EPOCH);
         let ctime = fstat.created().unwrap_or(std::time::UNIX_EPOCH);

gix-index/src/extension/tree/verify.rs

@@ -4,7 +4,7 @@ use bstr::{BString, ByteSlice};
 
 use crate::extension::Tree;
 
-/// The error returned by [Tree::verify()][crate::extension::Tree::verify()].
+/// The error returned by [`Tree::verify()`][crate::extension::Tree::verify()].
 #[derive(Debug, thiserror::Error)]
 #[allow(missing_docs)]
 pub enum Error {

gix-index/src/verify.rs

@@ -6,7 +6,7 @@ use crate::State;
 pub mod entries {
     use bstr::BString;
 
-    /// The error returned by [State::verify_entries()][crate::State::verify_entries()].
+    /// The error returned by [`State::verify_entries()`][crate::State::verify_entries()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -30,7 +30,7 @@ pub mod extensions {
         None
     }
 
-    /// The error returned by [State::verify_extensions()][crate::State::verify_extensions()].
+    /// The error returned by [`State::verify_extensions()`][crate::State::verify_extensions()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

gix-lock/src/file.rs

@@ -17,7 +17,7 @@ impl File {
         self.inner.with_mut(|tf| f(tf.as_file_mut())).and_then(|res| res)
     }
     /// Close the lock file to prevent further writes and to save system resources.
-    /// A call to [Marker::commit()] is allowed on the [`Marker`] to write changes back to the resource.
+    /// A call to [`Marker::commit()`] is allowed on the [`Marker`] to write changes back to the resource.
     pub fn close(self) -> std::io::Result<Marker> {
         Ok(Marker {
             inner: self.inner.close()?,

gix-mailmap/src/snapshot/mod.rs

@@ -22,7 +22,7 @@ impl Snapshot {
 
     /// Create a new instance from `entries`.
     ///
-    /// These can be obtained using [crate::parse()].
+    /// These can be obtained using [`crate::parse()`].
     pub fn new<'a>(entries: impl IntoIterator<Item = crate::Entry<'a>>) -> Self {
         let mut snapshot = Self::default();
         snapshot.merge(entries);
@@ -54,7 +54,7 @@ impl Snapshot {
     /// Transform our acceleration structure into a list of entries.
     ///
     /// Note that the order is different from how they were obtained initially, and are explicitly ordered by
-    /// (old_email, old_name).
+    /// (`old_email`, `old_name`).
     pub fn entries(&self) -> Vec<crate::Entry<'_>> {
         let mut out = Vec::with_capacity(self.entries_by_old_email.len());
         for entry in &self.entries_by_old_email {

gix-object/src/commit/ref_iter.rs

@@ -51,7 +51,7 @@ impl<'a> CommitRefIter<'a> {
         Token::try_into_id(tree_id).ok_or_else(missing_field)
     }
 
-    /// Return all parent_ids as iterator.
+    /// Return all `parent_ids` as iterator.
     ///
     /// Parsing errors are ignored quietly.
     pub fn parent_ids(self) -> impl Iterator<Item = gix_hash::ObjectId> + 'a {

gix-object/src/lib.rs

@@ -37,7 +37,7 @@ pub(crate) mod parse;
 ///
 pub mod kind;
 
-/// The four types of objects that git differentiates. #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
+/// The four types of objects that git differentiates.
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 #[allow(missing_docs)]

gix-object/src/tree/mod.rs

@@ -11,7 +11,7 @@ pub mod write;
 
 /// The mode of items storable in a tree, similar to the file mode on a unix file system.
 ///
-/// Used in [mutable::Entry][crate::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 = "serde", derive(serde::Serialize, serde::Deserialize))]

gix-object/tests/encode/mod.rs

@@ -1,4 +1,4 @@
-/// Because the TryFrom implementations don't return proper errors
+/// Because the `TryFrom` implementations don't return proper errors
 /// on failure
 #[derive(Debug, thiserror::Error)]
 enum Error {

gix-odb/src/store_impls/dynamic/load_index.rs

@@ -101,7 +101,7 @@ impl super::Store {
         }
     }
 
-    /// load a new index (if not yet loaded), and return true if one was indeed loaded (leading to a state_id() change) of the current index.
+    /// load a new index (if not yet loaded), and return true if one was indeed loaded (leading to a `state_id()` change) of the current index.
     /// Note that interacting with the slot-map is inherently racy and we have to deal with it, being conservative in what we even try to load
     /// as our index might already be out-of-date as we try to use it to learn what's next.
     fn load_next_index(&self, mut index: arc_swap::Guard<Arc<SlotMapIndex>>) -> bool {

gix-pack/src/bundle/find.rs

@@ -19,7 +19,7 @@ impl crate::Bundle {
     }
 
     /// Special-use function to get an object given an index previously returned from
-    /// internal_find_pack_index.
+    /// `internal_find_pack_index`.
     ///
     /// # Panics
     ///

gix-pack/src/bundle/write/mod.rs

@@ -168,7 +168,7 @@ impl crate::Bundle {
     /// # Note
     ///
     /// As it sends portions of the input to a thread it requires the 'static lifetime for the interrupt flags. This can only
-    /// be satisfied by a static AtomicBool which is only suitable for programs that only run one of these operations at a time
+    /// be satisfied by a static `AtomicBool` which is only suitable for programs that only run one of these operations at a time
     /// or don't mind that all of them abort when the flag is set.
     pub fn write_to_directory_eagerly<P>(
         pack: impl io::Read + Send + 'static,