graph: make the ahead-behind docs clearer

Explain it in local-upstream branch terms so it's easier to grasp than
with the `one` and `two` naming from the merge-base code.

2 files changed, 18 insertions, 13 deletions

diff --git a/include/git2/graph.h b/include/git2/graph.h
index 5850aa6e2..a2710219e 100644
--- a/include/git2/graph.h
+++ b/include/git2/graph.h
@@ -23,13 +23,18 @@ GIT_BEGIN_DECL
 /**
  * Count the number of unique commits between two commit objects
  *
- * @param ahead number of commits, starting at `one`, unique from commits in `two`
- * @param behind number of commits, starting at `two`, unique from commits in `one`
+ * There is no need for branches containing the commits to have any
+ * upstream relationship, but it helps to think of one as a branch and
+ * the other as its upstream, the `ahead` and `behind` values will be
+ * what git would report for the branches.
+ *
+ * @param ahead number of unique from commits in `upstream`
+ * @param behind number of unique from commits in `local`
  * @param repo the repository where the commits exist
- * @param one one of the commits
- * @param two the other commit
+ * @param local the commit for local
+ * @param upstream the commit for upstream
  */
-GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *one, const git_oid *two);
+GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream);
 
 /** @} */
 GIT_END_DECL
diff --git a/src/graph.c b/src/graph.c
index cb1727924..277f588ca 100644
--- a/src/graph.c
+++ b/src/graph.c
@@ -147,25 +147,25 @@ on_error:
 }
 
 int git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo,
-	const git_oid *one, const git_oid *two)
+	const git_oid *local, const git_oid *upstream)
 {
 	git_revwalk *walk;
-	git_commit_list_node *commit1, *commit2;
+	git_commit_list_node *commit_u, *commit_l;
 
 	if (git_revwalk_new(&walk, repo) < 0)
 		return -1;
 
-	commit2 = git_revwalk__commit_lookup(walk, two);
-	if (commit2 == NULL)
+	commit_u = git_revwalk__commit_lookup(walk, upstream);
+	if (commit_u == NULL)
 		goto on_error;
 
-	commit1 = git_revwalk__commit_lookup(walk, one);
-	if (commit1 == NULL)
+	commit_l = git_revwalk__commit_lookup(walk, local);
+	if (commit_l == NULL)
 		goto on_error;
 
-	if (mark_parents(walk, commit1, commit2) < 0)
+	if (mark_parents(walk, commit_l, commit_u) < 0)
 		goto on_error;
-	if (ahead_behind(commit1, commit2, ahead, behind) < 0)
+	if (ahead_behind(commit_l, commit_u, ahead, behind) < 0)
 		goto on_error;
 
 	git_revwalk_free(walk);