Update docs for new callback return value behavior

13 files changed, 91 insertions, 58 deletions

diff --git a/include/git2/attr.h b/include/git2/attr.h
index f256ff861..3adbb2c24 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -199,8 +199,9 @@ typedef int (*git_attr_foreach_cb)(const char *name, const char *value, void *pa
  *             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.
+ *             The value will be returned from `git_attr_foreach`.
  * @param payload Passed on as extra parameter to callback function.
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_attr_foreach(
 	git_repository *repo,
diff --git a/include/git2/config.h b/include/git2/config.h
index 3ab58f1a7..f650f1b41 100644
--- a/include/git2/config.h
+++ b/include/git2/config.h
@@ -450,13 +450,13 @@ GIT_EXTERN(int) git_config_delete_multivar(git_config *cfg, const char *name, co
  *
  * The callback receives the normalized name and value of each variable
  * in the config backend, and the data pointer passed to this function.
- * As soon as one of the callback functions returns something other than 0,
- * this function stops iterating and returns `GIT_EUSER`.
+ * If the callback returns a non-zero value, the function stops iterating
+ * and returns that value to the caller.
  *
  * @param cfg where to get the variables from
  * @param callback the function to call on each variable
  * @param payload the data to pass to the callback
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_config_foreach(
 	const git_config *cfg,
diff --git a/include/git2/diff.h b/include/git2/diff.h
index d6919393a..76fb23654 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -870,7 +870,7 @@ GIT_EXTERN(int) git_diff_is_sorted_icase(const git_diff *diff);
  * 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`.
+ * the iteration and return the value to the user.
  *
  * @param diff A git_diff generated by one of the above functions.
  * @param file_cb Callback function to make per file in the diff.
@@ -881,7 +881,7 @@ GIT_EXTERN(int) git_diff_is_sorted_icase(const git_diff *diff);
  *                same callback will be made for context lines, added, and
  *                removed lines, and even for a deleted trailing newline.
  * @param payload Reference pointer that will be passed to your callbacks.
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_diff_foreach(
 	git_diff *diff,
@@ -918,13 +918,13 @@ typedef enum {
  * Iterate over a diff generating formatted text output.
  *
  * Returning a non-zero value from the callbacks will terminate the
- * iteration and cause this return `GIT_EUSER`.
+ * iteration and return the non-zero value to the caller.
  *
  * @param diff A git_diff generated by one of the above functions.
  * @param format A git_diff_format_t value to pick the text format.
  * @param print_cb Callback to make per line of diff text.
  * @param payload Reference pointer that will be passed to your callback.
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_diff_print(
 	git_diff *diff,
@@ -964,7 +964,7 @@ GIT_EXTERN(int) git_diff_print(
  * @param hunk_cb Callback for each hunk in diff; can be NULL
  * @param line_cb Callback for each line in diff; can be NULL
  * @param payload Payload passed to each callback function
- * @return 0 on success, GIT_EUSER on non-zero callback return, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_diff_blobs(
 	const git_blob *old_blob,
@@ -999,7 +999,7 @@ GIT_EXTERN(int) git_diff_blobs(
  * @param hunk_cb Callback for each hunk in diff; can be NULL
  * @param line_cb Callback for each line in diff; can be NULL
  * @param payload Payload passed to each callback function
- * @return 0 on success, GIT_EUSER on non-zero callback return, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_diff_blob_to_buffer(
 	const git_blob *old_blob,
diff --git a/include/git2/errors.h b/include/git2/errors.h
index 26f9a747c..973d56003 100644
--- a/include/git2/errors.h
+++ b/include/git2/errors.h
@@ -19,25 +19,38 @@ GIT_BEGIN_DECL
 
 /** Generic return codes */
 typedef enum {
-	GIT_OK = 0,
-	GIT_ERROR = -1,
-	GIT_ENOTFOUND = -3,
-	GIT_EEXISTS = -4,
-	GIT_EAMBIGUOUS = -5,
-	GIT_EBUFS = -6,
-	GIT_EUSER = -7,
-	GIT_EBAREREPO = -8,
-	GIT_EUNBORNBRANCH = -9,
-	GIT_EUNMERGED = -10,
-	GIT_ENONFASTFORWARD = -11,
-	GIT_EINVALIDSPEC = -12,
-	GIT_EMERGECONFLICT = -13,
-	GIT_ELOCKED = -14,
+	GIT_OK         =  0,		/*< No error */
 
-	GIT_PASSTHROUGH = -30,
-	GIT_ITEROVER = -31,
+	GIT_ERROR      = -1,		/*< Generic error */
+	GIT_ENOTFOUND  = -3,		/*< Requested object could not be found */
+	GIT_EEXISTS    = -4,		/*< Object exists preventing operation */
+	GIT_EAMBIGUOUS = -5,		/*< More than one object matches */
+	GIT_EBUFS      = -6,		/*< Output buffer too short to hold data */
+
+	/* GIT_EUSER is a special error that is never generated by libgit2
+	 * code.  You can return it from a callback (e.g to stop an iteration)
+	 * to know that it was generated by the callback and not by libgit2.
+	 */
+	GIT_EUSER      = -7,
+
+	GIT_EBAREREPO       =  -8,	/*< Operation not allowed on bare repository */
+	GIT_EUNBORNBRANCH   =  -9,	/*< HEAD refers to branch with no commits */
+	GIT_EUNMERGED       = -10,	/*< Merge in progress prevented operation */
+	GIT_ENONFASTFORWARD = -11,	/*< Reference was not fast-forwardable */
+	GIT_EINVALIDSPEC    = -12,	/*< Name/ref spec was not in a valid format */
+	GIT_EMERGECONFLICT  = -13,	/*< Merge conflicts prevented operation */
+	GIT_ELOCKED         = -14,	/*< Lock file prevented operation */
+
+	GIT_PASSTHROUGH     = -30,	/*< Internal only */
+	GIT_ITEROVER        = -31,	/*< Signals end of iteration with iterator */
 } git_error_code;
 
+/**
+ * Structure to store extra details of the last error that occurred.
+ *
+ * This is kept on a per-thread basis if GIT_THREADS was defined when the
+ * library was build, otherwise one is kept globally for the library
+ */
 typedef struct {
 	char *message;
 	int klass;
diff --git a/include/git2/index.h b/include/git2/index.h
index a60db370a..ffefad15d 100644
--- a/include/git2/index.h
+++ b/include/git2/index.h
@@ -493,7 +493,7 @@ GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path);
  * item in the working directory immediately *before* it is added to /
  * updated in the index.  Returning zero will add the item to the index,
  * greater than zero will skip the item, and less than zero will abort the
- * scan and cause GIT_EUSER to be returned.
+ * scan and return that value to the caller.
  *
  * @param index an existing index object
  * @param pathspec array of path patterns
@@ -502,7 +502,7 @@ GIT_EXTERN(int) git_index_remove_bypath(git_index *index, const char *path);
  *                 gets index of matching pathspec entry); can be NULL;
  *                 return 0 to add, >0 to skip, <0 to abort scan.
  * @param payload payload passed through to callback function
- * @return 0 or an error code
+ * @return 0 on success, negative callback return value, or error code
  */
 GIT_EXTERN(int) git_index_add_all(
 	git_index *index,
@@ -524,7 +524,7 @@ GIT_EXTERN(int) git_index_add_all(
  *                 gets index of matching pathspec entry); can be NULL;
  *                 return 0 to add, >0 to skip, <0 to abort scan.
  * @param payload payload passed through to callback function
- * @return 0 or an error code
+ * @return 0 on success, negative callback return value, or error code
  */
 GIT_EXTERN(int) git_index_remove_all(
 	git_index *index,
@@ -553,7 +553,7 @@ GIT_EXTERN(int) git_index_remove_all(
  *                 gets index of matching pathspec entry); can be NULL;
  *                 return 0 to add, >0 to skip, <0 to abort scan.
  * @param payload payload passed through to callback function
- * @return 0 or an error code
+ * @return 0 on success, negative callback return value, or error code
  */
 GIT_EXTERN(int) git_index_update_all(
 	git_index *index,
diff --git a/include/git2/notes.h b/include/git2/notes.h
index 76361633b..0cb6ce5f1 100644
--- a/include/git2/notes.h
+++ b/include/git2/notes.h
@@ -189,7 +189,7 @@ GIT_EXTERN(int) git_note_default_ref(const char **out, git_repository *repo);
  *
  * @param payload Extra parameter to callback function.
  *
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_note_foreach(
 	git_repository *repo,
diff --git a/include/git2/odb.h b/include/git2/odb.h
index ad56384f0..82df4d300 100644
--- a/include/git2/odb.h
+++ b/include/git2/odb.h
@@ -189,7 +189,7 @@ GIT_EXTERN(int) git_odb_refresh(struct git_odb *db);
  * @param db database to use
  * @param cb the callback to call for each object
  * @param payload data to pass to the callback
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload);
 
diff --git a/include/git2/patch.h b/include/git2/patch.h
index 6a6ad92d7..e09f625c0 100644
--- a/include/git2/patch.h
+++ b/include/git2/patch.h
@@ -218,13 +218,13 @@ GIT_EXTERN(size_t) git_patch_size(
  * Serialize the patch to text via callback.
  *
  * Returning a non-zero value from the callback will terminate the iteration
- * and cause this return `GIT_EUSER`.
+ * and return that value to the caller.
  *
  * @param patch A git_patch representing changes to one file
  * @param print_cb Callback function to output lines of the patch.  Will be
  *                 called for file headers, hunk headers, and diff lines.
  * @param payload Reference pointer that will be passed to your callbacks.
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_patch_print(
 	git_patch *patch,
diff --git a/include/git2/push.h b/include/git2/push.h
index 77ef74039..12f0e7f2c 100644
--- a/include/git2/push.h
+++ b/include/git2/push.h
@@ -132,17 +132,19 @@ GIT_EXTERN(int) git_push_finish(git_push *push);
 GIT_EXTERN(int) git_push_unpack_ok(git_push *push);
 
 /**
- * Call callback `cb' on each status
+ * Invoke callback `cb' on each status entry
  *
  * For each of the updated references, we receive a status report in the
  * form of `ok refs/heads/master` or `ng refs/heads/master <msg>`.
  * `msg != NULL` means the reference has not been updated for the given
  * reason.
  *
+ * Return a non-zero value from the callback to stop the loop.
+ *
  * @param push The push object
  * @param cb The callback to call on each object
  *
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_push_status_foreach(git_push *push,
 			int (*cb)(const char *ref, const char *msg, void *data),
diff --git a/include/git2/refs.h b/include/git2/refs.h
index 4041947f6..e2bfa9615 100644
--- a/include/git2/refs.h
+++ b/include/git2/refs.h
@@ -310,20 +310,33 @@ typedef int (*git_reference_foreach_name_cb)(const char *name, void *payload);
  * Perform a callback on each reference in the repository.
  *
  * The `callback` function will be called for each reference in the
- * repository, receiving the name of the reference and the `payload` value
+ * repository, receiving the reference object and the `payload` value
  * passed to this method.  Returning a non-zero value from the callback
  * will terminate the iteration.
  *
  * @param repo Repository where to find the refs
  * @param callback Function which will be called for every listed ref
  * @param payload Additional data to pass to the callback
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_reference_foreach(
 	git_repository *repo,
 	git_reference_foreach_cb callback,
 	void *payload);
 
+/**
+ * Perform a callback on the fully-qualified name of each reference.
+ *
+ * The `callback` function will be called for each reference in the
+ * repository, receiving the name of the reference and the `payload` value
+ * passed to this method.  Returning a non-zero value from the callback
+ * will terminate the iteration.
+ *
+ * @param repo Repository where to find the refs
+ * @param callback Function which will be called for every listed ref name
+ * @param payload Additional data to pass to the callback
+ * @return 0 on success, non-zero callback return value, or error code
+ */
 GIT_EXTERN(int) git_reference_foreach_name(
 	git_repository *repo,
 	git_reference_foreach_name_cb callback,
diff --git a/include/git2/repository.h b/include/git2/repository.h
index c6bd4dca4..9f71d2959 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -503,14 +503,18 @@ typedef int (*git_repository_fetchhead_foreach_cb)(const char *ref_name,
 	void *payload);
 
 /**
- * Call callback 'callback' for each entry in the given FETCH_HEAD file.
+ * Invoke 'callback' for each entry in the given FETCH_HEAD file.
+ *
+ * Return a non-zero value from the callback to stop the loop.
  *
  * @param repo A repository object
  * @param callback Callback function
  * @param payload Pointer to callback data (optional)
- * @return 0 on success, GIT_ENOTFOUND, GIT_EUSER or error
+ * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if
+ *         there is no FETCH_HEAD file, or other error code.
  */
-GIT_EXTERN(int) git_repository_fetchhead_foreach(git_repository *repo,
+GIT_EXTERN(int) git_repository_fetchhead_foreach(
+	git_repository *repo,
 	git_repository_fetchhead_foreach_cb callback,
 	void *payload);
 
@@ -518,15 +522,19 @@ typedef int (*git_repository_mergehead_foreach_cb)(const git_oid *oid,
 	void *payload);
 
 /**
- * If a merge is in progress, call callback 'cb' for each commit ID in the
+ * If a merge is in progress, invoke 'callback' for each commit ID in the
  * MERGE_HEAD file.
  *
+ * Return a non-zero value from the callback to stop the loop.
+ *
  * @param repo A repository object
  * @param callback Callback function
  * @param payload Pointer to callback data (optional)
- * @return 0 on success, GIT_ENOTFOUND, GIT_EUSER or error
+ * @return 0 on success, non-zero callback return value, GIT_ENOTFOUND if
+ *         there is no MERGE_HEAD file, or other error code.
  */
-GIT_EXTERN(int) git_repository_mergehead_foreach(git_repository *repo,
+GIT_EXTERN(int) git_repository_mergehead_foreach(
+	git_repository *repo,
 	git_repository_mergehead_foreach_cb callback,
 	void *payload);
 
diff --git a/include/git2/stash.h b/include/git2/stash.h
index b48d33f5d..e2fe2cf0b 100644
--- a/include/git2/stash.h
+++ b/include/git2/stash.h
@@ -62,19 +62,15 @@ GIT_EXTERN(int) git_stash_save(
 	unsigned int flags);
 
 /**
- * When iterating over all the stashed states, callback that will be
- * issued per entry.
+ * This is a callback function you can provide to iterate over all the
+ * stashed states that will be invoked per entry.
  *
  * @param index The position within the stash list. 0 points to the
- * most recent stashed state.
- *
+ *              most recent stashed state.
  * @param message The stash message.
- *
  * @param stash_id The commit oid of the stashed state.
- *
  * @param payload Extra parameter to callback function.
- *
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 to continue iterating or non-zero to stop
  */
 typedef int (*git_stash_cb)(
 	size_t index,
@@ -89,12 +85,12 @@ typedef int (*git_stash_cb)(
  *
  * @param repo Repository where to find the stash.
  *
- * @param callback Callback to invoke per found stashed state. The most recent
- * stash state will be enumerated first.
+ * @param callback Callback to invoke per found stashed state. The most
+ *                 recent stash state will be enumerated first.
  *
  * @param payload Extra parameter to callback function.
  *
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_stash_foreach(
 	git_repository *repo,
diff --git a/include/git2/status.h b/include/git2/status.h
index 4ec3432df..aa68c0da0 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -203,12 +203,12 @@ typedef struct {
  * into this function.
  *
  * If the callback returns a non-zero value, this function will stop looping
- * and return GIT_EUSER.
+ * and return that value to caller.
  *
  * @param repo A repository object
  * @param callback The function to call on each file
  * @param payload Pointer to pass through to callback function
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_status_foreach(
 	git_repository *repo,
@@ -227,7 +227,7 @@ GIT_EXTERN(int) git_status_foreach(
  * @param opts Status options structure
  * @param callback The function to call on each file
  * @param payload Pointer to pass through to callback function
- * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ * @return 0 on success, non-zero callback return value, or error code
  */
 GIT_EXTERN(int) git_status_foreach_ext(
 	git_repository *repo,