Re: [PATCH v2 1/4] delete_ref: accept a reflog message argument

From: Kyle Meyer <kyle@kyleam.com>
Date: Feb 25, 2017, 03:05 UTC
Message-ID: <87poi7c6n2.fsf@kyleam.com>
In-Reply-To: <CACsJy8BJgL1i85nZ9CpAXCKaG+PQQkjRKLFPWzbsMF8WN8TEjQ@mail.gmail.com>

Duy Nguyen <pclouds@gmail.com> writes:

> You'll probably want to update the comment block above if msg can be
> NULL. We have _very_ good documentation in this file, let's keep it
> uptodate.

Looking at how other functions in refs.h document their "msg" or "logmsg" parameter, none seem to mention it explicitly. update_ref refers to ref_transaction_update, and ref_transaction_{update,create,delete,verify} refer to ref.h's "Reference transaction updates" comment.

delete_ref's docstring already mentions that "flag" is passed to ref_transaction_delete, so perhaps it should mention "msg" here as well.

-- >8 --
Subject: [PATCH] delete_ref: mention "msg" parameter in docstring

delete_ref() was recently extended to take a "msg" argument.
---
 refs.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/refs.h b/refs.h
index e529f4c3a..988750218 100644
--- a/refs.h
+++ b/refs.h
@@ -274,7 +274,8 @@ int reflog_exists(const char *refname);
  * verify that the current value of the reference is old_sha1 before
  * deleting it. If old_sha1 is NULL, delete the reference if it
  * exists, regardless of its old value. It is an error for old_sha1 to
- * be NULL_SHA1. flags is passed through to ref_transaction_delete().
+ * be NULL_SHA1. msg and flags are passed through to
+ * ref_transaction_delete().
  */
 int delete_ref(const char *msg, const char *refname,
 	       const unsigned char *old_sha1, unsigned int flags);

-- 
2.11.1