Fixing up some comments in strarray.h

include/git2/strarray.h

@@ -28,10 +28,16 @@ struct _git_strarray {
 /**
  * Close a string array object
  *
- * This method must always be called once a git_strarray is no
- * longer needed, otherwise memory will leak.
+ * 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.
  *
- * @param array array to close
+ * 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).
+ *
+ * @param array git_strarray from which to free string data
  */
 GIT_EXTERN(void) git_strarray_free(git_strarray *array);
 
@@ -43,6 +49,7 @@ GIT_EXTERN(void) git_strarray_free(git_strarray *array);
  *
  * @param tgt target
  * @param src source
+ * @return 0 on success, < 0 on allocation failure
  */
 GIT_EXTERN(int) git_strarray_copy(git_strarray *tgt, const git_strarray *src);