From 64a62ff8fe9fc826a8337a8e38b1886efbf53c99 Mon Sep 17 00:00:00 2001
From: Ed Page <eopage@gmail.com>
Date: Thu, 18 Jul 2024 20:48:10 -0500
Subject: [PATCH] docs(test): Expand 'git' documentation

---
 crates/cargo-test-support/src/git.rs | 31 ++++++++++++++++------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/crates/cargo-test-support/src/git.rs b/crates/cargo-test-support/src/git.rs
index e0b0c7a47..803e4dafd 100644
--- a/crates/cargo-test-support/src/git.rs
+++ b/crates/cargo-test-support/src/git.rs
@@ -1,10 +1,11 @@
 //! # Git Testing Support
 //!
 //! ## Creating a git dependency
-//! `git::new()` is an easy way to create a new git repository containing a
+//! [`new()`] is an easy way to create a new git repository containing a
 //! project that you can then use as a dependency. It will automatically add all
 //! the files you specify in the project and commit them to the repository.
-//! Example:
+//!
+//! ### Example:
 //!
 //! ```no_run
 //! # use cargo_test_support::project;
@@ -31,7 +32,8 @@
 //! ```
 //!
 //! ## Manually creating repositories
-//! `git::repo()` can be used to create a `RepoBuilder` which provides a way of
+//!
+//! [`repo()`] can be used to create a [`RepoBuilder`] which provides a way of
 //! adding files to a blank repository and committing them.
 //!
 //! If you want to then manipulate the repository (such as adding new files or
@@ -44,17 +46,21 @@ use std::path::{Path, PathBuf};
 use std::sync::Once;
 use url::Url;
 
+/// Manually construct a [`Repository`]
+///
+/// See also [`new`], [`repo`]
 #[must_use]
 pub struct RepoBuilder {
     repo: git2::Repository,
     files: Vec<PathBuf>,
 }
 
+/// See [`new`]
 pub struct Repository(git2::Repository);
 
-/// Create a `RepoBuilder` to build a new git repository.
+/// Create a [`RepoBuilder`] to build a new git repository.
 ///
-/// Call `build()` to finalize and create the repository.
+/// Call [`RepoBuilder::build()`] to finalize and create the repository.
 pub fn repo(p: &Path) -> RepoBuilder {
     RepoBuilder::init(p)
 }
@@ -130,7 +136,7 @@ impl Repository {
     }
 }
 
-/// Initialize a new repository at the given path.
+/// *(`git2`)* Initialize a new repository at the given path.
 pub fn init(path: &Path) -> git2::Repository {
     default_search_path();
     let repo = t!(git2::Repository::init(path));
@@ -158,7 +164,7 @@ fn default_repo_cfg(repo: &git2::Repository) {
     t!(cfg.set_str("user.name", "Foo Bar"));
 }
 
-/// Create a new git repository with a project.
+/// Create a new [`Project`] in a git [`Repository`]
 pub fn new<F>(name: &str, callback: F) -> Project
 where
     F: FnOnce(ProjectBuilder) -> ProjectBuilder,
@@ -166,8 +172,7 @@ where
     new_repo(name, callback).0
 }
 
-/// Create a new git repository with a project.
-/// Returns both the Project and the git Repository.
+/// Create a new [`Project`] with access to the [`Repository`]
 pub fn new_repo<F>(name: &str, callback: F) -> (Project, git2::Repository)
 where
     F: FnOnce(ProjectBuilder) -> ProjectBuilder,
@@ -182,14 +187,14 @@ where
     (git_project, repo)
 }
 
-/// Add all files in the working directory to the git index.
+/// *(`git2`)* Add all files in the working directory to the git index
 pub fn add(repo: &git2::Repository) {
     let mut index = t!(repo.index());
     t!(index.add_all(["*"].iter(), git2::IndexAddOption::DEFAULT, None));
     t!(index.write());
 }
 
-/// Add a git submodule to the repository.
+/// *(`git2`)* Add a git submodule to the repository
 pub fn add_submodule<'a>(
     repo: &'a git2::Repository,
     url: &str,
@@ -207,7 +212,7 @@ pub fn add_submodule<'a>(
     s
 }
 
-/// Commit changes to the git repository.
+/// *(`git2`)* Commit changes to the git repository
 pub fn commit(repo: &git2::Repository) -> git2::Oid {
     let tree_id = t!(t!(repo.index()).write_tree());
     let sig = t!(repo.signature());
@@ -226,7 +231,7 @@ pub fn commit(repo: &git2::Repository) -> git2::Oid {
     ))
 }
 
-/// Create a new tag in the git repository.
+/// *(`git2`)* Create a new tag in the git repository
 pub fn tag(repo: &git2::Repository, name: &str) {
     let head = repo.head().unwrap().target().unwrap();
     t!(repo.tag(