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, 10 insertions, 11 deletions

diff --git a/include/git2/attr.h b/include/git2/attr.h
index fad7183da..73a625a7e 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -172,18 +172,17 @@ GIT_EXTERN(int) git_attr_get_many(
  *
  * @param repo The repository containing the path.
  * @param flags A combination of GIT_ATTR_CHECK... flags.
- * @param path The path inside the repo to check attributes.  This
- *             does not have to exist, but if it does not, then
- *             it will be treated as a plain file (i.e. not a directory).
- * @param callback The function that will be invoked on each attribute
- *             and attribute value.  The name parameter will be the name
- *             of the attribute and the value will be the value it is
- *             set to, including possibly NULL if the attribute is
- *             explicitly set to UNSPECIFIED using the ! sign.  This
- *             will be invoked only once per attribute name, even if
- *             there are multiple rules for a given file.  The highest
- *             priority rule will be used.
+ * @param path Path inside the repo to check attributes.  This does not have
+ *             to exist, but if it does not, then it will be treated as a
+ *             plain file (i.e. not a directory).
+ * @param callback Function to invoke on each attribute name and value.  The
+ *             value may be NULL is the attribute is explicitly set to
+ *             UNSPECIFIED using the '!' sign.  Callback will be invoked
+ *             only once per attribute name, even if there are multiple
+ *             rules for a given file.  The highest priority rule will be
+ *             used.  Return a non-zero value from this to stop looping.
  * @param payload Passed on as extra parameter to callback function.
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_attr_foreach(
 	git_repository *repo,