Commit 373cf6a932a64d1cbe5f5cd8333546dcc2ca0b92

Russell Belfer 2013-12-09T10:17:47

Update docs for new callback return value behavior

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
diff --git a/include/git2/attr.h b/include/git2/attr.h
index f256ff8..3adbb2c 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 3ab58f1..f650f1b 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 d691939..76fb236 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 26f9a74..973d560 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 a60db37..ffefad1 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 7636163..0cb6ce5 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 ad56384..82df4d3 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 6a6ad92..e09f625 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 77ef740..12f0e7f 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 4041947..e2bfa96 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 c6bd4dc..9f71d29 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 b48d33f..e2fe2cf 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 4ec3432..aa68c0d 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,