Use *Blamed File* and *Source File* more consistently

This change also reflects the way `blamed_file` and `source_file` are
used throughout the code.

Author: cruessler

gix-blame/src/file/function.rs

@@ -37,7 +37,8 @@ use crate::{BlameEntry, Error, Options, Outcome, Statistics};
 ///
 /// *For brevity, `HEAD` denotes the starting point of the blame operation. It could be any commit, or even commits that
 /// represent the worktree state.
-/// We begin with a single *Unblamed Hunk* and a single suspect, usually the `HEAD` commit as the commit containing the
+///
+/// We begin with one or more *Unblamed Hunks* and a single suspect, usually the `HEAD` commit as the commit containing the
 /// *Blamed File*, so that it contains the entire file, with the first commit being a candidate for the entire *Blamed File*.
 /// We traverse the commit graph starting at the first suspect, and see if there have been changes to `file_path`.
 /// If so, we have found a *Source File* and a *Suspect* commit, and have hunks that represent these changes.

gix-blame/src/file/mod.rs

@@ -8,11 +8,12 @@ use crate::types::{BlameEntry, Change, Either, LineRange, Offset, UnblamedHunk};
 
 pub(super) mod function;
 
-/// Compare a section from the *Blamed File* (`hunk`) with a change from a diff and see if there
-/// is an intersection with `change`. Based on that intersection, we may generate a [`BlameEntry`] for `out`
-/// and/or split the `hunk` into multiple.
+/// Compare a section from a potential *Source File* (`hunk`) with a change from a diff and see if
+/// there is an intersection with `change`. Based on that intersection, we may generate a
+/// [`BlameEntry`] for `out` and/or split the `hunk` into multiple.
 ///
-/// This is the core of the blame implementation as it matches regions in *Source File* to the *Blamed File*.
+/// This is the core of the blame implementation as it matches regions in *Blamed File* to
+/// corresponding regions in one or more than one *Source File*.
 fn process_change(
     new_hunks_to_blame: &mut Vec<UnblamedHunk>,
     offset: &mut Offset,

gix-blame/src/lib.rs

@@ -2,10 +2,10 @@
 //!
 //! ### Terminology
 //!
-//! * **Source File**
-//!    - The file as it exists in `HEAD`.
-//!    - the initial state with all lines that we need to associate with a *Source File*.
 //! * **Blamed File**
+//!    - The file as it exists in `HEAD`.
+//!    - the initial state with all lines that we need to associate with a *Blamed File*.
+//! * **Source File**
 //!    - A file at a version (i.e. commit) that introduces hunks into the final 'image'.
 //! * **Suspects**
 //!    - The versions of the files that can contain hunks that we could use in the final 'image'