refs: document do_for_each_ref() and do_one_ref()
Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Haggerty committed
Apr 22, 2013 at 21:52 UTC
fcce17039cb94e6490a65a846b2375081785ce9b
1 file changed
+14
-1
refs.c
+14
-1
@@ -526,10 +526,14 @@ static void sort_ref_dir(struct ref_dir *dir)
526
dir->sorted = dir->nr = i;
527
}
528
529
-#define DO_FOR_EACH_INCLUDE_BROKEN 01
529
+/* Include broken references in a do_for_each_ref*() iteration: */
530
+#define DO_FOR_EACH_INCLUDE_BROKEN 0x01
531
532
static struct ref_entry *current_ref;
533
534
+/*
535
+ * Handle one reference in a do_for_each_ref*()-style iteration.
536
+ */
537
static int do_one_ref(const char *base, each_ref_fn fn, int trim,
538
int flags, void *cb_data, struct ref_entry *entry)
539
{
@@ -1339,6 +1343,15 @@ void warn_dangling_symref(FILE *fp, const char *msg_fmt, const char *refname)
1343
for_each_rawref(warn_if_dangling_symref, &data);
1344
}
1345
1346
+/*
1347
+ * Call fn for each reference in the specified submodule for which the
1348
+ * refname begins with base. If trim is non-zero, then trim that many
1349
+ * characters off the beginning of each refname before passing the
1350
+ * refname to fn. flags can be DO_FOR_EACH_INCLUDE_BROKEN to include
1351
+ * broken references in the iteration. If fn ever returns a non-zero
1352
+ * value, stop the iteration and return that value; otherwise, return
1353
+ * 0.
1354
+ */
1355
static int do_for_each_ref(const char *submodule, const char *base, each_ref_fn fn,
1356
int trim, int flags, void *cb_data)
1357
{