[PATCH 0/6] unused parameters: the final countdown

[PATCH 0/6] unused parameters: the final countdown

[Jeff King]

After many long sets of patches fixing and annotating existing cases,
this is the culminating series that actually turns on -Wunused-parameter
in our DEVELOPER=1 builds.

When applied on 'master', everything should compile cleanly with the new
warning. There are some new cases introduced in 'next', but I'll send
separate patches to go on those individual topics.

The first two patches fix new spots that cropped up since the last round
of fixes. Patches 3-5 address compat/ code. And then the interesting one
is patch 6.

  [1/6]: gc: mark unused config parameter in virtual functions
  [2/6]: t-reftable-readwrite: mark unused parameter in callback function
  [3/6]: compat: disable -Wunused-parameter in 3rd-party code
  [4/6]: compat: disable -Wunused-parameter in win32/headless.c
  [5/6]: compat: mark unused parameters in win32/mingw functions
  [6/6]: config.mak.dev: enable -Wunused-parameter by default

 builtin/gc.c                        | 16 ++++++++--------
 compat/mingw.c                      | 15 ++++++++-------
 compat/mingw.h                      | 18 +++++++++---------
 compat/nedmalloc/nedmalloc.c        |  2 ++
 compat/regex/regcomp.c              |  2 ++
 compat/stub/procinfo.c              |  2 +-
 compat/win32/headless.c             |  2 ++
 compat/win32/pthread.c              |  2 +-
 compat/win32/pthread.h              |  4 ++--
 compat/win32/syslog.c               |  2 +-
 compat/win32mmap.c                  |  2 +-
 compat/winansi.c                    |  2 +-
 config.mak.dev                      |  1 -
 t/unit-tests/t-reftable-readwrite.c |  2 +-
 14 files changed, 39 insertions(+), 33 deletions(-)

-Peff

[PATCH 1/6] gc: mark unused config parameter in virtual functions

[Jeff King]

Commit d1ae15d68b (builtin/gc: refactor to read config into structure,
2024-08-16) added a new parameter to the maintenance_task virtual
functions, but most of them don't need to look at it.

Signed-off-by: Jeff King <peff@peff.net>
---
 builtin/gc.c | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/builtin/gc.c b/builtin/gc.c
index 427faf1cfe..0e361253e3 100644
--- a/builtin/gc.c
+++ b/builtin/gc.c
@@ -967,7 +967,7 @@ static int dfs_on_ref(const char *refname UNUSED,
 	return result;
 }
 
-static int should_write_commit_graph(struct gc_config *cfg)
+static int should_write_commit_graph(struct gc_config *cfg UNUSED)
 {
 	int result;
 	struct cg_auto_data data;
@@ -1005,7 +1005,7 @@ static int run_write_commit_graph(struct maintenance_run_opts *opts)
 }
 
 static int maintenance_task_commit_graph(struct maintenance_run_opts *opts,
-					 struct gc_config *cfg)
+					 struct gc_config *cfg UNUSED)
 {
 	prepare_repo_settings(the_repository);
 	if (!the_repository->settings.core_commit_graph)
@@ -1040,7 +1040,7 @@ static int fetch_remote(struct remote *remote, void *cbdata)
 }
 
 static int maintenance_task_prefetch(struct maintenance_run_opts *opts,
-				     struct gc_config *cfg)
+				     struct gc_config *cfg UNUSED)
 {
 	if (for_each_remote(fetch_remote, opts)) {
 		error(_("failed to prefetch remotes"));
@@ -1051,7 +1051,7 @@ static int maintenance_task_prefetch(struct maintenance_run_opts *opts,
 }
 
 static int maintenance_task_gc(struct maintenance_run_opts *opts,
-			       struct gc_config *cfg)
+			       struct gc_config *cfg UNUSED)
 {
 	struct child_process child = CHILD_PROCESS_INIT;
 
@@ -1100,7 +1100,7 @@ static int loose_object_count(const struct object_id *oid UNUSED,
 	return 0;
 }
 
-static int loose_object_auto_condition(struct gc_config *cfg)
+static int loose_object_auto_condition(struct gc_config *cfg UNUSED)
 {
 	int count = 0;
 
@@ -1192,12 +1192,12 @@ static int pack_loose(struct maintenance_run_opts *opts)
 }
 
 static int maintenance_task_loose_objects(struct maintenance_run_opts *opts,
-					  struct gc_config *cfg)
+					  struct gc_config *cfg UNUSED)
 {
 	return prune_packed(opts) || pack_loose(opts);
 }
 
-static int incremental_repack_auto_condition(struct gc_config *cfg)
+static int incremental_repack_auto_condition(struct gc_config *cfg UNUSED)
 {
 	struct packed_git *p;
 	int incremental_repack_auto_limit = 10;
@@ -1317,7 +1317,7 @@ static int multi_pack_index_repack(struct maintenance_run_opts *opts)
 }
 
 static int maintenance_task_incremental_repack(struct maintenance_run_opts *opts,
-					       struct gc_config *cfg)
+					       struct gc_config *cfg UNUSED)
 {
 	prepare_repo_settings(the_repository);
 	if (!the_repository->settings.core_multi_pack_index) {
-- 
2.46.0.754.g24c813f009

[PATCH 2/6] t-reftable-readwrite: mark unused parameter in callback function

[Jeff King]

This spot was originally marked in in 4695c3f3a9 (reftable: mark unused
parameters in virtual functions, 2024-08-17), but was copied in
5b539a5361 (t: move reftable/readwrite_test.c to the unit testing
framework, 2024-08-13).

Signed-off-by: Jeff King <peff@peff.net>
---
 t/unit-tests/t-reftable-readwrite.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/t/unit-tests/t-reftable-readwrite.c b/t/unit-tests/t-reftable-readwrite.c
index 1eae36cc60..178296891c 100644
--- a/t/unit-tests/t-reftable-readwrite.c
+++ b/t/unit-tests/t-reftable-readwrite.c
@@ -26,7 +26,7 @@ static ssize_t strbuf_add_void(void *b, const void *data, size_t sz)
 	return sz;
 }
 
-static int noop_flush(void *arg)
+static int noop_flush(void *arg UNUSED)
 {
 	return 0;
 }
-- 
2.46.0.754.g24c813f009

[PATCH 3/6] compat: disable -Wunused-parameter in 3rd-party code

[Jeff King]

We carry some vendored 3rd-party code in compat/ that does not build
cleanly with -Wunused-parameters. We could mark these with UNUSED, but
there are two reasons not to:

  1. This is code imported from elsewhere, so we'd prefer to avoid
     modifying it in an invasive way that could create conflicts if we
     tried to pull in a new version.

  2. These files don't include git-compat-util.h at all, so we'd need to
     factor out (or repeat) our UNUSED macro.

In theory we could modify the build process to invoke the compiler with
the extra warning disabled for these files, but there are tricky corner
cases there (e.g., for NO_REGEX we cannot assume that the compiler
understands -Wno-unused-parameter as an option, so we'd have to use our
detect-compiler script).

Instead, let's rely on the gcc diagnostic #pragma. This is horribly
unportable, of course, but it should do what we want.  Compilers which
don't understand this particular pragma should ignore it (per the
standard), and compilers which do care about "-Wunused-parameter" will
hopefully respect it, even if they are not gcc (e.g., clang does).

Signed-off-by: Jeff King <peff@peff.net>
---
 compat/nedmalloc/nedmalloc.c | 2 ++
 compat/regex/regcomp.c       | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/compat/nedmalloc/nedmalloc.c b/compat/nedmalloc/nedmalloc.c
index 2c0ace7075..145255da43 100644
--- a/compat/nedmalloc/nedmalloc.c
+++ b/compat/nedmalloc/nedmalloc.c
@@ -31,6 +31,8 @@ DEALINGS IN THE SOFTWARE.
 /*#pragma optimize("a", on)*/
 #endif
 
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+
 /*#define FULLSANITYCHECKS*/
 
 #include "nedmalloc.h"
diff --git a/compat/regex/regcomp.c b/compat/regex/regcomp.c
index 6c5d455e92..8d93a9b93f 100644
--- a/compat/regex/regcomp.c
+++ b/compat/regex/regcomp.c
@@ -17,6 +17,8 @@
    License along with the GNU C Library; if not, see
    <http://www.gnu.org/licenses/>.  */
 
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+
 #if defined __TANDEM
  /* This is currently duplicated from git-compat-utils.h */
 # ifdef NO_INTPTR_T
-- 
2.46.0.754.g24c813f009

[PATCH 4/6] compat: disable -Wunused-parameter in win32/headless.c

[Jeff King]

As with the files touched in the previous commit, win32/headless.c does
not include git-compat-util.h, so it doesn't have our UNUSED macro.
Unlike those ones, this is not third-party code, so it would not be a
big deal to modify it.

However, I'm not sure if including git-compat-util.h would create other
headaches (and I don't even have a machine to test this on; I'm relying
on Windows CI to compile it at all). Given how trivial the file is, and
that the unused parameters are not interesting (they are just
boilerplate for the wWinMain() function), we can just use the same trick
as the previous commit and disable the warnings via pragma.

Signed-off-by: Jeff King <peff@peff.net>
---
 compat/win32/headless.c | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/compat/win32/headless.c b/compat/win32/headless.c
index 8b00dfe3bd..11392a0b9a 100644
--- a/compat/win32/headless.c
+++ b/compat/win32/headless.c
@@ -11,6 +11,8 @@
 #include <stdlib.h>
 #include <wchar.h>
 
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+
 /*
  * If `dir` contains the path to a Git exec directory, extend `PATH` to
  * include the corresponding `bin/` directory (which is where all those
-- 
2.46.0.754.g24c813f009

[PATCH 5/6] compat: mark unused parameters in win32/mingw functions

[Jeff King]

The compat/ directory contains many stub functions, wrappers, and so on
that have to conform to a specific interface, but don't necessarily need
to use all of their parameters. Let's mark them to avoid complaints from
-Wunused-parameter.

This was done mostly via guess-and-check with the Windows build in
GitHub CI. I also confirmed that the win+VS build is similarly happy.

Signed-off-by: Jeff King <peff@peff.net>
---
 compat/mingw.c         | 15 ++++++++-------
 compat/mingw.h         | 18 +++++++++---------
 compat/stub/procinfo.c |  2 +-
 compat/win32/pthread.c |  2 +-
 compat/win32/pthread.h |  4 ++--
 compat/win32/syslog.c  |  2 +-
 compat/win32mmap.c     |  2 +-
 compat/winansi.c       |  2 +-
 8 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/compat/mingw.c b/compat/mingw.c
index 29d3f09768..eb13c02a76 100644
--- a/compat/mingw.c
+++ b/compat/mingw.c
@@ -243,7 +243,8 @@ static enum hide_dotfiles_type hide_dotfiles = HIDE_DOTFILES_DOTGITONLY;
 static char *unset_environment_variables;
 
 int mingw_core_config(const char *var, const char *value,
-		      const struct config_context *ctx, void *cb)
+		      const struct config_context *ctx UNUSED,
+		      void *cb UNUSED)
 {
 	if (!strcmp(var, "core.hidedotfiles")) {
 		if (value && !strcasecmp(value, "dotgitonly"))
@@ -453,7 +454,7 @@ static int set_hidden_flag(const wchar_t *path, int set)
 	return -1;
 }
 
-int mingw_mkdir(const char *path, int mode)
+int mingw_mkdir(const char *path, int mode UNUSED)
 {
 	int ret;
 	wchar_t wpath[MAX_PATH];
@@ -597,7 +598,7 @@ int mingw_open (const char *filename, int oflags, ...)
 	return fd;
 }
 
-static BOOL WINAPI ctrl_ignore(DWORD type)
+static BOOL WINAPI ctrl_ignore(DWORD type UNUSED)
 {
 	return TRUE;
 }
@@ -1085,7 +1086,7 @@ int mkstemp(char *template)
 	return git_mkstemp_mode(template, 0600);
 }
 
-int gettimeofday(struct timeval *tv, void *tz)
+int gettimeofday(struct timeval *tv, void *tz UNUSED)
 {
 	FILETIME ft;
 	long long hnsec;
@@ -2252,7 +2253,7 @@ char *mingw_query_user_email(void)
 	return get_extended_user_info(NameUserPrincipal);
 }
 
-struct passwd *getpwuid(int uid)
+struct passwd *getpwuid(int uid UNUSED)
 {
 	static unsigned initialized;
 	static char user_name[100];
@@ -2304,7 +2305,7 @@ static sig_handler_t timer_fn = SIG_DFL, sigint_fn = SIG_DFL;
  * length to call the signal handler.
  */
 
-static unsigned __stdcall ticktack(void *dummy)
+static unsigned __stdcall ticktack(void *dummy UNUSED)
 {
 	while (WaitForSingleObject(timer_event, timer_interval) == WAIT_TIMEOUT) {
 		mingw_raise(SIGALRM);
@@ -2352,7 +2353,7 @@ static inline int is_timeval_eq(const struct timeval *i1, const struct timeval *
 	return i1->tv_sec == i2->tv_sec && i1->tv_usec == i2->tv_usec;
 }
 
-int setitimer(int type, struct itimerval *in, struct itimerval *out)
+int setitimer(int type UNUSED, struct itimerval *in, struct itimerval *out)
 {
 	static const struct timeval zero;
 	static int atexit_done;
diff --git a/compat/mingw.h b/compat/mingw.h
index 27b61284f4..ebfb8ba423 100644
--- a/compat/mingw.h
+++ b/compat/mingw.h
@@ -122,27 +122,27 @@ struct utsname {
  * trivial stubs
  */
 
-static inline int readlink(const char *path, char *buf, size_t bufsiz)
+static inline int readlink(const char *path UNUSED, char *buf UNUSED, size_t bufsiz UNUSED)
 { errno = ENOSYS; return -1; }
-static inline int symlink(const char *oldpath, const char *newpath)
+static inline int symlink(const char *oldpath UNUSED, const char *newpath UNUSED)
 { errno = ENOSYS; return -1; }
-static inline int fchmod(int fildes, mode_t mode)
+static inline int fchmod(int fildes UNUSED, mode_t mode UNUSED)
 { errno = ENOSYS; return -1; }
 #ifndef __MINGW64_VERSION_MAJOR
 static inline pid_t fork(void)
 { errno = ENOSYS; return -1; }
 #endif
-static inline unsigned int alarm(unsigned int seconds)
+static inline unsigned int alarm(unsigned int seconds UNUSED)
 { return 0; }
 static inline int fsync(int fd)
 { return _commit(fd); }
 static inline void sync(void)
 {}
 static inline uid_t getuid(void)
 { return 1; }
-static inline struct passwd *getpwnam(const char *name)
+static inline struct passwd *getpwnam(const char *name UNUSED)
 { return NULL; }
-static inline int fcntl(int fd, int cmd, ...)
+static inline int fcntl(int fd UNUSED, int cmd, ...)
 {
 	if (cmd == F_GETFD || cmd == F_SETFD)
 		return 0;
@@ -151,17 +151,17 @@ static inline int fcntl(int fd, int cmd, ...)
 }
 
 #define sigemptyset(x) (void)0
-static inline int sigaddset(sigset_t *set, int signum)
+static inline int sigaddset(sigset_t *set UNUSED, int signum UNUSED)
 { return 0; }
 #define SIG_BLOCK 0
 #define SIG_UNBLOCK 0
-static inline int sigprocmask(int how, const sigset_t *set, sigset_t *oldset)
+static inline int sigprocmask(int how UNUSED, const sigset_t *set UNUSED, sigset_t *oldset UNUSED)
 { return 0; }
 static inline pid_t getppid(void)
 { return 1; }
 static inline pid_t getpgid(pid_t pid)
 { return pid == 0 ? getpid() : pid; }
-static inline pid_t tcgetpgrp(int fd)
+static inline pid_t tcgetpgrp(int fd UNUSED)
 { return getpid(); }
 
 /*
diff --git a/compat/stub/procinfo.c b/compat/stub/procinfo.c
index 12c0a23c9e..3168cd5714 100644
--- a/compat/stub/procinfo.c
+++ b/compat/stub/procinfo.c
@@ -6,6 +6,6 @@
  * Stub. See sample implementations in compat/linux/procinfo.c and
  * compat/win32/trace2_win32_process_info.c.
  */
-void trace2_collect_process_info(enum trace2_process_info_reason reason)
+void trace2_collect_process_info(enum trace2_process_info_reason reason UNUSED)
 {
 }
diff --git a/compat/win32/pthread.c b/compat/win32/pthread.c
index 85f8f7920c..58980a529c 100644
--- a/compat/win32/pthread.c
+++ b/compat/win32/pthread.c
@@ -21,7 +21,7 @@ static unsigned __stdcall win32_start_routine(void *arg)
 	return 0;
 }
 
-int pthread_create(pthread_t *thread, const void *unused,
+int pthread_create(pthread_t *thread, const void *attr UNUSED,
 		   void *(*start_routine)(void *), void *arg)
 {
 	thread->arg = arg;
diff --git a/compat/win32/pthread.h b/compat/win32/pthread.h
index cc3221cb2c..e2b5c4f64c 100644
--- a/compat/win32/pthread.h
+++ b/compat/win32/pthread.h
@@ -18,7 +18,7 @@
  */
 #define pthread_mutex_t CRITICAL_SECTION
 
-static inline int return_0(int i) {
+static inline int return_0(int i UNUSED) {
 	return 0;
 }
 #define pthread_mutex_init(a,b) return_0((InitializeCriticalSection((a)), 0))
@@ -70,7 +70,7 @@ static inline void NORETURN pthread_exit(void *ret)
 }
 
 typedef DWORD pthread_key_t;
-static inline int pthread_key_create(pthread_key_t *keyp, void (*destructor)(void *value))
+static inline int pthread_key_create(pthread_key_t *keyp, void (*destructor)(void *value) UNUSED)
 {
 	return (*keyp = TlsAlloc()) == TLS_OUT_OF_INDEXES ? EAGAIN : 0;
 }
diff --git a/compat/win32/syslog.c b/compat/win32/syslog.c
index 0af18d8882..4e4794743a 100644
--- a/compat/win32/syslog.c
+++ b/compat/win32/syslog.c
@@ -2,7 +2,7 @@
 
 static HANDLE ms_eventlog;
 
-void openlog(const char *ident, int logopt, int facility)
+void openlog(const char *ident, int logopt UNUSED, int facility UNUSED)
 {
 	if (ms_eventlog)
 		return;
diff --git a/compat/win32mmap.c b/compat/win32mmap.c
index 519d51f2b6..a4ab4cb939 100644
--- a/compat/win32mmap.c
+++ b/compat/win32mmap.c
@@ -40,7 +40,7 @@ void *git_mmap(void *start, size_t length, int prot, int flags, int fd, off_t of
 	return MAP_FAILED;
 }
 
-int git_munmap(void *start, size_t length)
+int git_munmap(void *start, size_t length UNUSED)
 {
 	return !UnmapViewOfFile(start);
 }
diff --git a/compat/winansi.c b/compat/winansi.c
index 575813bde8..1b3f916b9f 100644
--- a/compat/winansi.c
+++ b/compat/winansi.c
@@ -340,7 +340,7 @@ enum {
 	TEXT = 0, ESCAPE = 033, BRACKET = '['
 };
 
-static DWORD WINAPI console_thread(LPVOID unused)
+static DWORD WINAPI console_thread(LPVOID data UNUSED)
 {
 	unsigned char buffer[BUFFER_SIZE];
 	DWORD bytes;
-- 
2.46.0.754.g24c813f009

[PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

[Jeff King]

Having now removed or annotated all of the unused function parameters in
our code base, I found that each instance falls into one of three
categories:

  1. ignoring the parameter is a bug (e.g., a function takes a ptr/len
     pair, but ignores the length). Detecting these helps us find the
     bugs.

  2. the parameter is unnecessary (and usually left over from a
     refactoring or earlier iteration of a patches series). Removing
     these cleans up the code.

  3. the function has to conform to a specific interface (because it's
     used via a function pointer, or matches something on the other side
     of an #ifdef). These ones are annoying, but annotating them with
     UNUSED is not too bad (especially if the compiler tells you about
     the problem promptly).

Certainly instances of (3) are more common than (1), but after finding
all of these, I think there were enough cases of (1) that it justifies
the work in annotating all of the (3)s.

And since the code base is now at a spot where we compile cleanly with
-Wunused-parameter, turning it on will make it the responsibility of
individual patch writers going forward.

Signed-off-by: Jeff King <peff@peff.net>
---
 config.mak.dev | 1 -
 1 file changed, 1 deletion(-)

diff --git a/config.mak.dev b/config.mak.dev
index 5229c35484..50026d1e0e 100644
--- a/config.mak.dev
+++ b/config.mak.dev
@@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
 DEVELOPER_CFLAGS += -Wno-empty-body
 DEVELOPER_CFLAGS += -Wno-missing-field-initializers
 DEVELOPER_CFLAGS += -Wno-sign-compare
-DEVELOPER_CFLAGS += -Wno-unused-parameter
 endif
 endif
 
-- 
2.46.0.754.g24c813f009

Re: [PATCH 0/6] unused parameters: the final countdown

[Jeff King]

On Tue, Aug 27, 2024 at 11:57:23PM -0400, Jeff King wrote:

> When applied on 'master', everything should compile cleanly with the new
> warning. There are some new cases introduced in 'next', but I'll send
> separate patches to go on those individual topics.

Those are at:

  https://lore.kernel.org/git/20240828040944.GA4005021@coredump.intra.peff.net/

and:

  https://lore.kernel.org/git/20240828040803.GA4004932@coredump.intra.peff.net/

I double-checked against what's in 'seen', and there's nothing new
there. Of course I won't be surprised if something new pops up while
this topic is cooking, but CI will start catching it in any branch where
this is merged (and the solution is usually pretty obvious).

-Peff

Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

[Eric Sunshine]

On Wed, Aug 28, 2024 at 12:01 AM Jeff King <peff@peff.net> wrote:
> Having now removed or annotated all of the unused function parameters in
> our code base, I found that each instance falls into one of three
> categories:
>
>   1. ignoring the parameter is a bug (e.g., a function takes a ptr/len
>      pair, but ignores the length). Detecting these helps us find the
>      bugs.
>
>   2. the parameter is unnecessary (and usually left over from a
>      refactoring or earlier iteration of a patches series). Removing
>      these cleans up the code.
>
>   3. the function has to conform to a specific interface (because it's
>      used via a function pointer, or matches something on the other side
>      of an #ifdef). These ones are annoying, but annotating them with
>      UNUSED is not too bad (especially if the compiler tells you about
>      the problem promptly).
> [...]
> And since the code base is now at a spot where we compile cleanly with
> -Wunused-parameter, turning it on will make it the responsibility of
> individual patch writers going forward.
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> diff --git a/config.mak.dev b/config.mak.dev
> @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
>  DEVELOPER_CFLAGS += -Wno-sign-compare
> -DEVELOPER_CFLAGS += -Wno-unused-parameter

What is the expectation regarding newcomers to the project or even
people who have not been following this topic and its cousins?
Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
which is good, but this change means that such people may now be hit
with a compiler complaint which they don't necessarily know how to
deal with in the legitimate case #3 (described above). Should
CodingGuidelines be updated to mention "UNUSED" and the circumstances
under which it should be used?

Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

[Patrick Steinhardt]

On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote:
> On Wed, Aug 28, 2024 at 12:01 AM Jeff King <peff@peff.net> wrote:
> > Having now removed or annotated all of the unused function parameters in
> > our code base, I found that each instance falls into one of three
> > categories:
> >
> >   1. ignoring the parameter is a bug (e.g., a function takes a ptr/len
> >      pair, but ignores the length). Detecting these helps us find the
> >      bugs.
> >
> >   2. the parameter is unnecessary (and usually left over from a
> >      refactoring or earlier iteration of a patches series). Removing
> >      these cleans up the code.
> >
> >   3. the function has to conform to a specific interface (because it's
> >      used via a function pointer, or matches something on the other side
> >      of an #ifdef). These ones are annoying, but annotating them with
> >      UNUSED is not too bad (especially if the compiler tells you about
> >      the problem promptly).
> > [...]
> > And since the code base is now at a spot where we compile cleanly with
> > -Wunused-parameter, turning it on will make it the responsibility of
> > individual patch writers going forward.
> >
> > Signed-off-by: Jeff King <peff@peff.net>
> > ---
> > diff --git a/config.mak.dev b/config.mak.dev
> > @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
> >  DEVELOPER_CFLAGS += -Wno-sign-compare
> > -DEVELOPER_CFLAGS += -Wno-unused-parameter
> 
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?

Updating our coding guidelines would certainly be welcome. Other than
that this series looks good to me and is a step into the right direction
in my opinion. Thanks!

Patrick

[PATCH 7/6] CodingGuidelines: mention -Wunused-parameter and UNUSED

[Jeff King]

On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote:

> > And since the code base is now at a spot where we compile cleanly with
> > -Wunused-parameter, turning it on will make it the responsibility of
> > individual patch writers going forward.
> [...]
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?

Yeah, I agree some guidance is in order. How about this on top? I didn't
go into the decision tree of when you should remove the parameter versus
using it versus annotating it. I think in general that the first two are
pretty obvious when they are appropriate, and we just need to focus on
the annotating option.

-- >8 --
Subject: [PATCH] CodingGuidelines: mention -Wunused-parameter and UNUSED

Now that -Wunused-parameter is on by default for DEVELOPER=1 builds,
people may trigger it, blocking their build. When it's a mistake for the
parameter to exist, the path forward is obvious: remove it. But
sometimes you need to suppress the warning, and the "UNUSED" mechanism
for that is specific to our project, so people may not know about it.

Let's put some advice in CodingGuidelines, including an example warning
message. That should help people who grep for the warning text after
seeing it from the compiler.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/CodingGuidelines | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index ccaea39752..d0fc7cfe60 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -258,6 +258,13 @@ For C programs:
    ensure your patch is clear of all compiler warnings we care about,
    by e.g. "echo DEVELOPER=1 >>config.mak".
 
+ - When using DEVELOPER=1 mode, you may see warnings from the compiler
+   like "error: unused parameter 'foo' [-Werror=unused-parameter]",
+   which indicates that a function ignores its argument. If the unused
+   parameter can't be removed (e.g., because the function is used as a
+   callback and has to match a certain interface), you can annotate the
+   individual parameters with the UNUSED keyword, like "int foo UNUSED".
+
  - We try to support a wide range of C compilers to compile Git with,
    including old ones.  As of Git v2.35.0 Git requires C99 (we check
    "__STDC_VERSION__"). You should not use features from a newer C
-- 
2.46.0.754.g24c813f009

Re: [PATCH 6/6] config.mak.dev: enable -Wunused-parameter by default

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

>>   3. the function has to conform to a specific interface (because it's
>>      used via a function pointer, or matches something on the other side
>>      of an #ifdef). These ones are annoying, but annotating them with
>>      UNUSED is not too bad (especially if the compiler tells you about
>>      the problem promptly).
>> [...]
>> And since the code base is now at a spot where we compile cleanly with
>> -Wunused-parameter, turning it on will make it the responsibility of
>> individual patch writers going forward.
>>
>> Signed-off-by: Jeff King <peff@peff.net>
>> ---
>> diff --git a/config.mak.dev b/config.mak.dev
>> @@ -54,7 +54,6 @@ ifeq ($(filter extra-all,$(DEVOPTS)),)
>>  DEVELOPER_CFLAGS += -Wno-sign-compare
>> -DEVELOPER_CFLAGS += -Wno-unused-parameter
>
> What is the expectation regarding newcomers to the project or even
> people who have not been following this topic and its cousins?
> Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> which is good, but this change means that such people may now be hit
> with a compiler complaint which they don't necessarily know how to
> deal with in the legitimate case #3 (described above). Should
> CodingGuidelines be updated to mention "UNUSED" and the circumstances
> under which it should be used?

I am not yet convinced 100%, but probably it is a good idea.

We have our idioms and conventions like use of UNLEAK(), UNUSED,
__attribute__ to annotate varargs functions that take printf-like
format, always using "{ 0 }" and no other form to zero-initialize an
auto variable of an aggregate type, etc., that are unreasonable for
somebody, who is new to the project but is fluent in and competent
at C, to know all of them.

For things like UNLEAK() that require a bit more than general
competence in the language, a bit more thought and peeking the
implementation to understand how they work, we should document them
to make it easier to learn for new people.  

Consistently using "{ 0 }", instead of picking a single random
member and initialize the aggrevate with "{ .it = 0 }", is asking
the writer to pick between two _valid_ C language constructs and
always use one of them, so it may make sense to document it, even
though the general "do what the existing code does" may be
sufficient.

Unlike them, UNUSED smells a lot more obvious, and because the
code base is full of API functions that take callback functions,
we have plenty of existing uses of it for those who are competent
but are unfamiliar to the code base to notice and pick up quickly.

So I have a feeling that relatively speaking it is less necessary to
help new contributors with documenting UNUSED than other conventions
we have.

I have no objection if somebody else does a thoughtful job to
document these things evenly, but if we are going to document
UNUSED, we should explicitly document that it is our policy to
document each and every one of these conventions to help new
contributors.

Thanks.

Re: [PATCH 7/6] CodingGuidelines: mention -Wunused-parameter and UNUSED

[Eric Sunshine]

On Wed, Aug 28, 2024 at 10:48 AM Jeff King <peff@peff.net> wrote:
> On Wed, Aug 28, 2024 at 01:56:13AM -0400, Eric Sunshine wrote:
> > What is the expectation regarding newcomers to the project or even
> > people who have not been following this topic and its cousins?
> > Documentation/CodingGuidelines recommends enabling DEVELOPER mode,
> > which is good, but this change means that such people may now be hit
> > with a compiler complaint which they don't necessarily know how to
> > deal with in the legitimate case #3 (described above). Should
> > CodingGuidelines be updated to mention "UNUSED" and the circumstances
> > under which it should be used?
>
> Yeah, I agree some guidance is in order. How about this on top? I didn't
> go into the decision tree of when you should remove the parameter versus
> using it versus annotating it. I think in general that the first two are
> pretty obvious when they are appropriate, and we just need to focus on
> the annotating option.
>
> -- >8 --
> Subject: [PATCH] CodingGuidelines: mention -Wunused-parameter and UNUSED
>
> Now that -Wunused-parameter is on by default for DEVELOPER=1 builds,
> people may trigger it, blocking their build. When it's a mistake for the
> parameter to exist, the path forward is obvious: remove it. But
> sometimes you need to suppress the warning, and the "UNUSED" mechanism
> for that is specific to our project, so people may not know about it.
>
> Let's put some advice in CodingGuidelines, including an example warning
> message. That should help people who grep for the warning text after
> seeing it from the compiler.

Makes sense.

> Signed-off-by: Jeff King <peff@peff.net>
> ---
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> @@ -258,6 +258,13 @@ For C programs:
> + - When using DEVELOPER=1 mode, you may see warnings from the compiler
> +   like "error: unused parameter 'foo' [-Werror=unused-parameter]",
> +   which indicates that a function ignores its argument. If the unused
> +   parameter can't be removed (e.g., because the function is used as a
> +   callback and has to match a certain interface), you can annotate the
> +   individual parameters with the UNUSED keyword, like "int foo UNUSED".

Perfect. This fully addresses the question expressed by my review
comment. Thank you.