Fixing up some comments in strarray.h

include/git2/strarray.h

@@ -28,21 +28,28 @@ 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);
 
 /**
  * Copy a string array object from source to target.
- * 
- * Note: target is overwritten and hence should be empty, 
+ *
+ * Note: target is overwritten and hence should be empty,
  * otherwise its contents are leaked.
  *
  * @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);
 
@@ -51,4 +58,4 @@ GIT_EXTERN(int) git_strarray_copy(git_strarray *tgt, const git_strarray *src);
 GIT_END_DECL
 
 #endif
- 
+