strarray: we should dispose instead of free

We _dispose_ the contents of objects; we _free_ objects (and their
contents).  Update `git_strarray_free` to be `git_strarray_dispose`.
`git_strarray_free` remains as a deprecated proxy function.

Author: ethomson

examples/checkout.c

@@ -239,7 +239,7 @@ static int guess_refish(git_annotated_commit **out, git_repository *repo, const
 
 out:
 	git_reference_free(remote_ref);
-	git_strarray_free(&remotes);
+	git_strarray_dispose(&remotes);
 	return error;
 }
 

examples/general.c

@@ -707,7 +707,7 @@ static void reference_listing(git_repository *repo)
 		git_reference_free(ref);
 	}
 
-	git_strarray_free(&ref_list);
+	git_strarray_dispose(&ref_list);
 }
 
 /**

examples/remote.c

@@ -129,7 +129,7 @@ static int cmd_rename(git_repository *repo, struct remote_opts *o)
 		puts(problems.strings[0]);
 	}
 
-	git_strarray_free(&problems);
+	git_strarray_dispose(&problems);
 
 	return retval;
 }
@@ -207,7 +207,7 @@ static int cmd_show(git_repository *repo, struct remote_opts *o)
 		git_remote_free(remote);
 	}
 
-	git_strarray_free(&remotes);
+	git_strarray_dispose(&remotes);
 
 	return 0;
 }

examples/tag.c

@@ -162,7 +162,7 @@ static void action_list_tags(tag_state *state)
 		each_tag(tag_names.strings[i], state);
 	}
 
-	git_strarray_free(&tag_names);
+	git_strarray_dispose(&tag_names);
 }
 
 static void action_delete_tag(tag_state *state)

include/git2/deprecated.h

@@ -524,6 +524,30 @@ typedef int GIT_CALLBACK(git_headlist_cb)(git_remote_head *rhead, void *payload)
 
 /**@}*/
 
+/** @name Deprecated String 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_strarray.  This is an alias of
+ * `git_strarray_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_strarray_dispose
+ * @see git_strarray_dispose
+ */
+GIT_EXTERN(void) git_strarray_free(git_strarray *array);
+
+/**@}*/
+
 /** @name Deprecated Options Initialization Functions
  *
  * These functions are retained for backward compatibility.  The newer

include/git2/strarray.h

@@ -25,20 +25,16 @@ typedef struct git_strarray {
 } git_strarray;
 
 /**
- * Close a string array object
- *
- * This method should be called on `git_strarray` objects where the strings
- * array is allocated and contains allocated strings, such as what you
- * would get from `git_strarray_copy()`.  Not doing so, will result in a
- * memory leak.
+ * Free the strings contained in a string array.  This method should
+ * be called on `git_strarray` objects that were provided by the
+ * library.  Not doing so, will result in a memory leak.
  *
  * This does not free the `git_strarray` 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_strarray from which to free string data
+ * @param array The git_strarray that contains strings to free
  */
-GIT_EXTERN(void) git_strarray_free(git_strarray *array);
+GIT_EXTERN(void) git_strarray_dispose(git_strarray *array);
 
 /**
  * Copy a string array object from source to target.

src/branch.c

@@ -548,7 +548,7 @@ int git_branch_remote_name(git_buf *buf, git_repository *repo, const char *refna
 	if (error < 0)
 		git_buf_dispose(buf);
 
-	git_strarray_free(&remote_list);
+	git_strarray_dispose(&remote_list);
 	return error;
 }
 

src/remote.c

@@ -1237,7 +1237,7 @@ static int prune_candidates(git_vector *candidates, git_remote *remote)
 	}
 
 out:
-	git_strarray_free(&arr);
+	git_strarray_dispose(&arr);
 	return error;
 }
 

src/repository.c

@@ -2289,7 +2289,7 @@ int git_repository_foreach_head(git_repository *repo,
 
 out:
 	git_buf_dispose(&path);
-	git_strarray_free(&worktrees);
+	git_strarray_dispose(&worktrees);
 	return error;
 }
 

src/strarray.c

@@ -29,7 +29,7 @@ int git_strarray_copy(git_strarray *tgt, const git_strarray *src)
 
 		tgt->strings[tgt->count] = git__strdup(src->strings[i]);
 		if (!tgt->strings[tgt->count]) {
-			git_strarray_free(tgt);
+			git_strarray_dispose(tgt);
 			memset(tgt, 0, sizeof(*tgt));
 			return -1;
 		}
@@ -40,7 +40,7 @@ int git_strarray_copy(git_strarray *tgt, const git_strarray *src)
 	return 0;
 }
 
-void git_strarray_free(git_strarray *array)
+void git_strarray_dispose(git_strarray *array)
 {
 	size_t i;
 
@@ -54,3 +54,8 @@ void git_strarray_free(git_strarray *array)
 
 	memset(array, 0, sizeof(*array));
 }
+
+void git_strarray_free(git_strarray *array)
+{
+	git_strarray_dispose(array);
+}