Subject: Re* [PATCH 2/4] refs: trim newline from reflog message

From: Junio C Hamano <[email-masked]>
Date: Fri, 26 Nov 2021 00:35:17 -0800

Junio C Hamano <[email-masked]> writes:

> I think what deserves such a comment more is the prototype for
> each_reflog_ent_fn describing what the parameters to that callback
> function, to help the callers of the iterator what to expect.  That
> is the end-user facing part.

Perhaps something along this line.

--- >8 ------ >8 ------ >8 ------ >8 ------ >8 ------ >8 ---
Subject: [PATCH] refs: document callback for reflog-ent iterators

refs_for_each_reflog_ent() and refs_for_each_reflog_ent_reverse()
functions take a callback function that gets called with the details
of each reflog entry.  Its parameters were not documented beyond
their names.  Elaborate a bit on each of them.

Signed-off-by: Junio C Hamano <[email-masked]>
---
 refs.h | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git c/refs.h w/refs.h
index 48970dfc7e..4fa97d77cf 100644
--- c/refs.h
+++ w/refs.h
@@ -462,7 +462,27 @@ int delete_reflog(const char *refname);
 
 /*
  * Callback to process a reflog entry found by the iteration functions (see
- * below)
+ * below).
+ *
+ * The committer parameter is a single string, in the form
+ * "$GIT_COMMITTER_NAME <$GIT_COMMITTER_EMAIL>" (without double quotes).
+ *
+ * The timestamp parameter gives the seconds since epoch when the reflog
+ * entry was created.
+ *
+ * The tz parameter is an up to 4 digits integer, whose absolute value
+ * gives the hour and minute offset from GMT (the lower 2 digits are
+ * minutes, the higher 2 digits are hours).  A negative tz means west of,
+ * and a positive tz means east of GMT.
+ *
+ * The msg parameter is a single complete line; a reflog message given
+ * to refs_delete_ref, refs_update_ref, etc. is returned to the
+ * callback normalized---each run of whitespaces are squashed into a
+ * single whitespace, trailing whitespace, if exists, is trimmed, and
+ * then a single LF is added at the end.
+ *
+ * The cb_data is a caller-supplied pointer given to the iterator
+ * functions.
  */
 typedef int each_reflog_ent_fn(
 		struct object_id *old_oid, struct object_id *new_oid,