Update iterators for consistency across library

This updates all the `foreach()` type functions across the library
that take callbacks from the user to have a consistent behavior.
The rules are:

* A callback terminates the loop by returning any non-zero value
* Once the callback returns non-zero, it will not be called again
  (i.e. the loop stops all iteration regardless of state)
* If the callback returns non-zero, the parent fn returns GIT_EUSER
* Although the parent returns GIT_EUSER, no error will be set in
  the library and `giterr_last()` will return NULL if called.

This commit makes those changes across the library and adds tests
for most of the iteration APIs to make sure that they follow the
above rules.

1 files changed, 18 insertions, 0 deletions

diff --git a/include/git2/diff.h b/include/git2/diff.h
index 85727d969..79ef7a49b 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -332,6 +332,9 @@ GIT_EXTERN(int) git_diff_merge(
  * callbacks will not be invoked for binary files on the diff list or for
  * files whose only changed is a file mode change.
  *
+ * Returning a non-zero value from any of the callbacks will terminate
+ * the iteration and cause this return `GIT_EUSER`.
+ *
  * @param diff A git_diff_list generated by one of the above functions.
  * @param cb_data Reference pointer that will be passed to your callbacks.
  * @param file_cb Callback function to make per file in the diff.
@@ -341,6 +344,7 @@ GIT_EXTERN(int) git_diff_merge(
  * @param line_cb Optional callback to make per line of diff text.  This
  *                same callback will be made for context lines, added, and
  *                removed lines, and even for a deleted trailing newline.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_foreach(
 	git_diff_list *diff,
@@ -351,6 +355,14 @@ GIT_EXTERN(int) git_diff_foreach(
 
 /**
  * Iterate over a diff generating text output like "git diff --name-status".
+ *
+ * Returning a non-zero value from the callbacks will terminate the
+ * iteration and cause this return `GIT_EUSER`.
+ *
+ * @param diff A git_diff_list generated by one of the above functions.
+ * @param cb_data Reference pointer that will be passed to your callback.
+ * @param print_cb Callback to make per line of diff text.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_print_compact(
 	git_diff_list *diff,
@@ -362,6 +374,9 @@ GIT_EXTERN(int) git_diff_print_compact(
  *
  * This is a super easy way to generate a patch from a diff.
  *
+ * Returning a non-zero value from the callbacks will terminate the
+ * iteration and cause this return `GIT_EUSER`.
+ *
  * @param diff A git_diff_list generated by one of the above functions.
  * @param cb_data Reference pointer that will be passed to your callbacks.
  * @param print_cb Callback function to output lines of the diff.  This
@@ -369,6 +384,7 @@ GIT_EXTERN(int) git_diff_print_compact(
  *                 headers, and diff lines.  Fortunately, you can probably
  *                 use various GIT_DIFF_LINE constants to determine what
  *                 text you are given.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_print_patch(
 	git_diff_list *diff,
@@ -393,6 +409,8 @@ GIT_EXTERN(int) git_diff_print_patch(
  * When at least one of the blobs being dealt with is binary, the
  * `git_diff_delta` binary attribute will be set to 1 and no call to the
  * hunk_cb nor line_cb will be made.
+ *
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_diff_blobs(
 	git_blob *old_blob,