Update docs for new callback return value behavior

1 files changed, 29 insertions, 16 deletions

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;