[PATCH 1/5] pretty.h: update and expand docstring for userformat_find_requirements()

From: Jeff King <peff@peff.net>
Date: Jun 22, 2021, 16:03 UTC
Message-ID: <YNIJ6tZMhn5wZ4Io@coredump.intra.peff.net>
In-Reply-To: <YNIJw/8p0F3cPfzd@coredump.intra.peff.net>

The comment only mentions "notes", but there are more fields now (and I'm about to add another). Let's make it more general, and stick the struct next to the function to make the list of possibilities obvious.

While we're touching this comment, let's also mention the behavior of NULL, which some callers rely on (though in the long run, this global is pretty nasty and probably should get moved into rev_info).

Signed-off-by: Jeff King <peff@peff.net>
---
 pretty.h | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/pretty.h b/pretty.h
index f034609e4d..c81cf40d38 100644
--- a/pretty.h
+++ b/pretty.h
@@ -65,12 +65,15 @@ static inline int cmit_fmt_is_mail(enum cmit_fmt fmt)
 	return (fmt == CMIT_FMT_EMAIL || fmt == CMIT_FMT_MBOXRD);
 }
 
+/*
+ * Examine the user-specified format given by "fmt" (or if NULL, the global one
+ * previously saved by get_commit_format()), and set flags based on which items
+ * the format will need when it is expanded.
+ */
 struct userformat_want {
 	unsigned notes:1;
 	unsigned source:1;
 };
-
-/* Set the flag "w->notes" if there is placeholder %N in "fmt". */
 void userformat_find_requirements(const char *fmt, struct userformat_want *w);
 
 /*

-- 
2.32.0.352.gff02c21e72