[PATCH 8/6] CodingGuidelines: also mention MAYBE_UNUSED
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Aug 29, 2024, 15:00 UTC
- Message-ID
- <xmqqseunxtks.fsf_-_@gitster.g>
- In-Reply-To
- <20240829040215.GA4054823@coredump.intra.peff.net>
Jeff King <peff@peff.net> writes:
Show 7 quoted lines
> On Wed, Aug 28, 2024 at 02:28:47PM -0700, Junio C Hamano wrote: > >> By the way, Peff, do we have MAYBE_UNUSED that can be used in a case >> like this one? Platforms without symbolic links supported may well >> define NO_SYMLINK_HEAD, which makes the incoming parameters unused. > > Yes, it would be fine to use MAYBE_UNUSED in a case like this.
It turns out that I was, without realizing it myself, making an oblique reference to your patch 7/6 ;-)
Perhaps something along this line?
---- >8 ---- Subject: CodingGuidelines: also mention MAYBE_UNUSED
A function that uses a parameter in one build may lose all uses of the parameter in another build, depending on the configuration. A workaround for such a case, MAYBE_UNUSED, should also be mentioned when we recommend the use of UNUSED to our developers.
Signed-off-by: Junio C Hamano <gitster@pobox.com> --- Documentation/CodingGuidelines | 5 +++-- git-compat-util.h | 21 +++++++++++++++++++++ 2 files changed, 24 insertions(+), 2 deletions(-)
diff --git c/Documentation/CodingGuidelines w/Documentation/CodingGuidelines index d0fc7cfe60..3263245b03 100644 --- c/Documentation/CodingGuidelines +++ w/Documentation/CodingGuidelines @@ -262,8 +262,9 @@ For C programs: 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". + callback and has to match a certain interface), you can annotate + the individual parameters with the UNUSED (or MAYBE_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 diff --git c/git-compat-util.h w/git-compat-util.h index 71b4d23f03..23307ce780 100644 --- c/git-compat-util.h +++ w/git-compat-util.h @@ -195,6 +195,17 @@ struct strbuf; #define _NETBSD_SOURCE 1 #define _SGI_SOURCE 1 +/* + * UNUSED marks a function parameter that is always unused. + * + * A callback interface may dictate that a function accepts a + * parameter at that position, but the implementation of the function + * may not need to use the parameter. In such a case, mark the parameter + * with UNUSED. + * + * When a parameter may be used or unused, depending on conditional + * compilation, consider using MAYBE_UNUSED instead. + */ #if GIT_GNUC_PREREQ(4, 5) #define UNUSED __attribute__((unused)) \ __attribute__((deprecated ("parameter declared as UNUSED"))) @@ -649,6 +660,16 @@ static inline int git_has_dir_sep(const char *path) #define RESULT_MUST_BE_USED #endif +/* + * MAYBE_UNUSED marks a function parameter that may be unused, but + * whose use is not an error. + * + * Depending on a configuration, all uses of a function parameter may + * become #ifdef'ed away. Marking such a parameter with UNUSED would + * give a warning in a compilation where the parameter is indeed used, + * and not marking such a parameter would give a warning in a + * compilation where the parameter is unused. + */ #define MAYBE_UNUSED __attribute__((__unused__)) #include "compat/bswap.h"