add all docs (GitoxideLabs#366)

Byron · Byron · commit 1c768a5511ba · 2022-03-28T21:01:32.000+08:00
diff --git a/git-mailmap/src/entry.rs b/git-mailmap/src/entry.rs
@@ -1,6 +1,10 @@
 use crate::Entry;
 use bstr::BStr;
 
+/// Constructors indicating what kind of mapping is created.
+///
+/// Only these combinations of values are valid.
+#[allow(missing_docs)]
 impl<'a> Entry<'a> {
     pub fn change_name_by_email(proper_name: impl Into<&'a BStr>, commit_email: impl Into<&'a BStr>) -> Self {
         Entry {
diff --git a/git-mailmap/src/lib.rs b/git-mailmap/src/lib.rs
@@ -1,37 +1,57 @@
 #![forbid(unsafe_code)]
-#![deny(rust_2018_idioms)]
+#![deny(rust_2018_idioms, missing_docs)]
+//! [Parse][parse()] .mailmap files as used in git repositories and remap names and emails
+//! using an [accelerated data-structure][Snapshot].
 
 use bstr::BStr;
 
+///
 pub mod parse;
+
+/// Parse the given `buf` of bytes line by line into mapping [Entries][Entry].
+///
+/// Errors may occour per line, but it's up to the caller to stop iteration when
+/// one is encountered.
 pub fn parse(buf: &[u8]) -> parse::Lines<'_> {
     parse::Lines::new(buf)
 }
 
+/// Similar to [parse()], but will skip all lines that didn't parse correctly, silently squelching all errors.
 pub fn parse_ignore_errors(buf: &[u8]) -> impl Iterator<Item = Entry<'_>> {
     parse(buf).filter_map(Result::ok)
 }
 
 mod entry;
 
+///
 pub mod snapshot;
 
+/// A data-structure to efficiently store a list of entries for optimal, case-insensitive lookup by email and
+/// optionally name to find mappings to new names and/or emails.
+///
+/// The memory layout is efficient, even though lots of small allocations are performed to store strings of emails and names.
 #[derive(Default, Clone)]
 pub struct Snapshot {
     /// Sorted by `old_email`
     entries_by_old_email: Vec<snapshot::EmailEntry>,
 }
 
+/// An typical entry of a mailmap, which always contains an `old_email` by which
+/// the mapping is performed to replace the given `new_name` and `new_email`.
+///
+/// Optionally, `old_name` is also used for lookup.
+///
+/// Typically created by [parse()].
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy, Default)]
 #[cfg_attr(feature = "serde1", derive(serde::Serialize, serde::Deserialize))]
 pub struct Entry<'a> {
     #[cfg_attr(feature = "serde1", serde(borrow))]
     /// The name to map to.
-    pub new_name: Option<&'a BStr>,
+    pub(crate) new_name: Option<&'a BStr>,
     /// The email map to.
-    pub new_email: Option<&'a BStr>,
+    pub(crate) new_email: Option<&'a BStr>,
     /// The name to look for and replace.
-    pub old_name: Option<&'a BStr>,
+    pub(crate) old_name: Option<&'a BStr>,
     /// The email to look for and replace.
-    pub old_email: &'a BStr,
+    pub(crate) old_email: &'a BStr,
 }
diff --git a/git-mailmap/src/parse.rs b/git-mailmap/src/parse.rs
@@ -3,7 +3,9 @@ mod error {
     use quick_error::quick_error;
 
     quick_error! {
+        /// The error returned by [`parse()`][crate::parse()].
         #[derive(Debug)]
+        #[allow(missing_docs)]
         pub enum Error {
             UnconsumedInput { line_number: usize, line: BString } {
                 display("Line {} has too many names or emails, or none at all: {}", line_number, line)
@@ -19,6 +21,7 @@ use crate::Entry;
 use bstr::{BStr, ByteSlice};
 pub use error::Error;
 
+/// An iterator to parse mailmap lines on-demand.
 pub struct Lines<'a> {
     lines: bstr::Lines<'a>,
     line_no: usize,
diff --git a/git-mailmap/src/snapshot.rs b/git-mailmap/src/snapshot.rs
@@ -4,8 +4,11 @@ use git_actor::SignatureRef;
 use std::cmp::Ordering;
 use std::ops::Deref;
 
+/// A resolved signature with borrowed fields for a mapped `name` and/or `email`.
 pub struct ResolvedSignature<'a> {
+    /// The mapped name.
     pub name: Option<&'a BStr>,
+    /// The mapped email.
     pub email: Option<&'a BStr>,
 }
 
@@ -165,16 +168,24 @@ impl<'a> From<crate::Entry<'a>> for EmailEntry {
 }
 
 impl Snapshot {
+    /// Create a new snapshot from the given bytes buffer, ignoring all parse errors that may occour on a line-by-line basis.
+    ///
+    /// This is similar to what git does.
     pub fn from_bytes(buf: &[u8]) -> Self {
         Self::new(crate::parse_ignore_errors(buf))
     }
 
+    /// Create a new instance from `entries`.
+    ///
+    /// 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);
         snapshot
     }
 
+    /// Merge the given `entries` into this instance, possibly overwriting existing mappings with
+    /// new ones should they collide.
     pub fn merge<'a>(&mut self, entries: impl IntoIterator<Item = crate::Entry<'a>>) -> &mut Self {
         for entry in entries {
             let old_email: EncodedStringRef<'_> = entry.old_email.into();
@@ -195,6 +206,10 @@ impl Snapshot {
         self
     }
 
+    /// Try to resolve `signature` by its contained email and name and provide resolved/mapped names as reference.
+    /// Return `None` if no such mapping was found.
+    ///
+    /// This is the fastest possible lookup as there is no allocation.
     pub fn try_resolve_ref<'a>(&'a self, signature: &git_actor::SignatureRef<'_>) -> Option<ResolvedSignature<'a>> {
         let email: EncodedStringRef<'_> = signature.email.into();
         let pos = self
@@ -214,11 +229,19 @@ impl Snapshot {
         }
     }
 
+    /// Try to resolve `signature` by its contained email and name and provide resolved/mapped names as owned signature,
+    /// with the mapped name and/or email replaced accordingly.
+    ///
+    /// Return `None` if no such mapping was found.
     pub fn try_resolve(&self, signature: &git_actor::SignatureRef<'_>) -> Option<git_actor::Signature> {
         let new = self.try_resolve_ref(signature)?;
         enriched_signature(signature, new)
     }
 
+    /// Like [`try_resolve()`][Snapshot::try_resolve()], but always returns an owned signature, which might be a copy
+    /// of `signature` if no mapping was found.
+    ///
+    /// Note that this method will always allocate.
     pub fn resolve(&self, signature: &git_actor::SignatureRef<'_>) -> git_actor::Signature {
         self.try_resolve(signature).unwrap_or_else(|| signature.to_owned())
     }
diff --git a/git-mailmap/tests/fixtures/overwrite.txt b/git-mailmap/tests/fixtures/overwrite.txt
@@ -9,3 +9,5 @@ B-overwritten <new-b-email-overwritten> <old-b-email>
 C <new-c-email> old-C <old-c-email>
 C-overwritten <new-c-email-overwritten> old-C <old-c-email>
 
+<new-d-email> <old-d-email>
+<new-d-email-overwritten> <old-d-email>
diff --git a/git-mailmap/tests/snapshot/mod.rs b/git-mailmap/tests/snapshot/mod.rs
@@ -54,19 +54,14 @@ fn try_resolve() {
 fn non_name_and_name_mappings_will_not_clash() {
     let entries = vec![
         // add mapping from email
-        git_mailmap::Entry {
-            new_name: Some("new-name".into()),
-            new_email: Some("new-email".into()),
-            old_name: None,
-            old_email: "old-email".into(),
-        },
+        git_mailmap::Entry::change_name_and_email_by_email("new-name", "new-email", "old-email"),
         // add mapping from name and email
-        git_mailmap::Entry {
-            new_name: Some("other-new-name".into()),
-            new_email: Some("other-new-email".into()),
-            old_name: Some("old-name".into()),
-            old_email: "old-email".into(),
-        },
+        git_mailmap::Entry::change_name_and_email_by_name_and_email(
+            "other-new-name",
+            "other-new-email",
+            "old-name",
+            "old-email",
+        ),
     ];
     for entries in vec![entries.clone().into_iter().rev().collect::<Vec<_>>(), entries] {
         let snapshot = Snapshot::new(entries);
@@ -104,6 +99,12 @@ fn overwrite_entries() {
         Some(signature("C-overwritten", "new-c-email-overwritten")),
         "name and email by name and email"
     );
+
+    assert_eq!(
+        snapshot.try_resolve(&signature("unchanged", "old-d-email").to_ref()),
+        Some(signature("unchanged", "new-d-email-overwritten")),
+        "email by email"
+    );
 }
 
 fn snapshot() -> Snapshot {
