document get_git_merge_base and get_closest_merge_commit in detail

Signed-off-by: onur-ozkan <work@onurozkan.dev>

Author: onur-ozkan

src/tools/build_helper/src/git.rs

@@ -96,6 +96,10 @@ pub fn updated_master_branch(
     Err("Cannot find any suitable upstream master branch".to_owned())
 }
 
+/// Finds the nearest merge commit by comparing the local `HEAD` with the upstream branch's state.
+/// To work correctly, the upstream remote must be properly configured using `git remote add <name> <url>`.
+/// In most cases `get_closest_merge_commit` is the function you are looking for as it doesn't require remote
+/// to be configured.
 fn get_git_merge_base(config: &GitConfig<'_>, git_dir: Option<&Path>) -> Result<String, String> {
     let updated_master = updated_master_branch(config, git_dir)?;
     let mut git = Command::new("git");
@@ -105,9 +109,10 @@ fn get_git_merge_base(config: &GitConfig<'_>, git_dir: Option<&Path>) -> Result<
     Ok(output_result(git.arg("merge-base").arg(&updated_master).arg("HEAD"))?.trim().to_owned())
 }
 
-/// Resolves the closest merge commit by the given `author` and `target_paths`.
+/// Searches for the nearest merge commit in the repository.
 ///
-/// If it fails to find the commit from upstream using `git merge-base`, fallbacks to HEAD.
+/// If it fails to find the upstream remote, it then looks for the most recent commit made
+/// by the merge bot by matching the author's email address with the merge bot's email.
 pub fn get_closest_merge_commit(
     git_dir: Option<&Path>,
     config: &GitConfig<'_>,