oidarray: introduce `git_oidarray_dispose`ethomson/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`.

2 files changed, 29 insertions, 8 deletions

diff --git a/include/git2/deprecated.h b/include/git2/deprecated.h
index 6b268eb79..37b9fa0e2 100644
--- a/include/git2/deprecated.h
+++ b/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
diff --git a/include/git2/oidarray.h b/include/git2/oidarray.h
index 0b3204597..94fc58dab 100644
--- a/include/git2/oidarray.h
+++ b/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