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, 4 insertions, 3 deletions

diff --git a/include/git2/odb.h b/include/git2/odb.h
index dac9e06a9..1f25db463 100644
--- a/include/git2/odb.h
+++ b/include/git2/odb.h
@@ -176,13 +176,14 @@ GIT_EXTERN(int) git_odb_exists(git_odb *db, const git_oid *id);
  * List all objects available in the database
  *
  * The callback will be called for each object available in the
- * database. Note that the objects are likely to be returned in the
- * index order, which would make accessing the objects in that order
- * inefficient.
+ * database. Note that the objects are likely to be returned in the index
+ * order, which would make accessing the objects in that order inefficient.
+ * Return a non-zero value from the callback to stop looping.
  *
  * @param db database to use
  * @param cb the callback to call for each object
  * @param data data to pass to the callback
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_odb_foreach(git_odb *db, int (*cb)(git_oid *oid, void *data), void *data);