buffer: deprecate `git_buf_free` in favor of `git_buf_dispose`

include/git2/buffer.h

@@ -69,7 +69,19 @@ typedef struct {
  *
  * @param buffer The buffer to deallocate
  */
-GIT_EXTERN(void) git_buf_free(git_buf *buffer);
+GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
+
+/**
+ * Alias of `git_buf_dispose`.
+ *
+ * This function is directly calls `git_buf_dispose` now and is deprecated.
+ * Going forward, we refer to functions freeing the internal state of a
+ * structure a `dispose` function, while functions freeing the structure
+ * themselves will be called a `free` function.
+ *
+ * This function is going to be removed in v0.30.0.
+ */
+GIT_EXTERN(void) GIT_DEPRECATED(git_buf_free)(git_buf *buffer);
 
 /**
  * Resize the buffer allocation to make more space.

src/buffer.c

@@ -116,7 +116,7 @@ int git_buf_grow_by(git_buf *buffer, size_t additional_size)
 	return git_buf_try_grow(buffer, newsize, true);
 }
 
-void git_buf_free(git_buf *buf)
+void git_buf_dispose(git_buf *buf)
 {
 	if (!buf) return;
 
@@ -126,6 +126,11 @@ void git_buf_free(git_buf *buf)
 	git_buf_init(buf, 0);
 }
 
+void git_buf_free(git_buf *buf)
+{
+	git_buf_dispose(buf);
+}
+
 void git_buf_sanitize(git_buf *buf)
 {
 	if (buf->ptr == NULL) {