oidarray: introduce `git_oidarray_dispose`

Since users are disposing the _contents_ of the oidarray, not freeing
the oidarray itself, the proper cleanup function is
`git_oidarray_dispose`.  Deprecate `git_oidarray_free`.

include/git2/deprecated.h

@@ -779,6 +779,30 @@ GIT_EXTERN(int) git_oid_iszero(const git_oid *id);
 
 /**@}*/
 
+/** @name Deprecated OID Array Functions
+ *
+ * These types are retained for backward compatibility.  The newer
+ * versions of these values should be preferred in all new code.
+ *
+ * There is no plan to remove these backward compatibility values at
+ * this time.
+ */
+/**@{*/
+
+/**
+ * Free the memory referred to by the git_oidarray.  This is an alias of
+ * `git_oidarray_dispose` and is preserved for backward compatibility.
+ *
+ * This function is deprecated, but there is no plan to remove this
+ * function at this time.
+ *
+ * @deprecated Use git_oidarray_dispose
+ * @see git_oidarray_dispose
+ */
+GIT_EXTERN(void) git_oidarray_free(git_oidarray *array);
+
+/**@}*/
+
 /** @name Deprecated Transfer Progress Types
  *
  * These types are retained for backward compatibility.  The newer

include/git2/oidarray.h

@@ -19,19 +19,16 @@ typedef struct git_oidarray {
 } git_oidarray;
 
 /**
- * Free the OID array
- *
- * This method must (and must only) be called on `git_oidarray`
- * objects where the array is allocated by the library. Not doing so,
- * will result in a memory leak.
+ * Free the object IDs contained in an oid_array.  This method should
+ * be called on `git_oidarray` objects that were provided by the
+ * library.  Not doing so will result in a memory leak.
  *
  * This does not free the `git_oidarray` itself, since the library will
- * never allocate that object directly itself (it is more commonly embedded
- * inside another struct or created on the stack).
+ * never allocate that object directly itself.
  *
  * @param array git_oidarray from which to free oid data
  */
-GIT_EXTERN(void) git_oidarray_free(git_oidarray *array);
+GIT_EXTERN(void) git_oidarray_dispose(git_oidarray *array);
 
 /** @} */
 GIT_END_DECL

src/merge.c

@@ -2369,7 +2369,7 @@ done:
 
 	git_annotated_commit_free(other);
 	git_annotated_commit_free(new_base);
-	git_oidarray_free(&bases);
+	git_oidarray_dispose(&bases);
 	git_array_clear(head_ids);
 	return error;
 }

src/oidarray.c

@@ -10,7 +10,7 @@
 #include "git2/oidarray.h"
 #include "array.h"
 
-void git_oidarray_free(git_oidarray *arr)
+void git_oidarray_dispose(git_oidarray *arr)
 {
 	git__free(arr->ids);
 }
@@ -32,3 +32,12 @@ void git_oidarray__reverse(git_oidarray *arr)
 		git_oid_cpy(&arr->ids[(arr->count-1)-i], &tmp);
 	}
 }
+
+#ifndef GIT_DEPRECATE_HARD
+
+void git_oidarray_free(git_oidarray *arr)
+{
+	git_oidarray_dispose(arr);
+}
+
+#endif

tests/revwalk/mergebase.c

@@ -150,7 +150,7 @@ void test_revwalk_mergebase__multiple_merge_bases(void)
 	cl_assert_equal_oid(&expected1, &result.ids[0]);
 	cl_assert_equal_oid(&expected2, &result.ids[1]);
 
-	git_oidarray_free(&result);
+	git_oidarray_dispose(&result);
 }
 
 void test_revwalk_mergebase__multiple_merge_bases_many_commits(void)
@@ -170,7 +170,7 @@ void test_revwalk_mergebase__multiple_merge_bases_many_commits(void)
 	cl_assert_equal_oid(&expected1, &result.ids[0]);
 	cl_assert_equal_oid(&expected2, &result.ids[1]);
 
-	git_oidarray_free(&result);
+	git_oidarray_dispose(&result);
 	git__free(input);
 }
 
@@ -509,6 +509,6 @@ void test_revwalk_mergebase__remove_redundant(void)
 	cl_assert_equal_i(1, result.count);
 	cl_assert_equal_oid(&base, &result.ids[0]);
 
-	git_oidarray_free(&result);
+	git_oidarray_dispose(&result);
 	git_repository_free(repo);
 }