development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-11-05 01:58:18 +00:00
Code Issues Projects Releases Packages Wiki Activity

CodingGuidelines: also mention MAYBE_UNUSED

Browse source 
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.

Keep the addition to the guideline short and document the criteria
to choose between UNUSED and MAYBE_UNUSED near their definition.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
Junio C Hamano 2024-08-29 11:18:06 -07:00
parent c3b92d4037
commit a051ca5e65
2 changed files with 27 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
Documentation/CodingGuidelines
View file

@ -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

24
git-compat-util.h
View file

@ -195,6 +195,19 @@ struct strbuf;
#define _NETBSD_SOURCE 1
#define _SGI_SOURCE 1
/*
* UNUSED marks a function parameter that is always unused. It also
* can be used to annotate a function, a variable, or a type 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 +662,17 @@ 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. It also can be used to annotate a
* function, a variable, or a type that may be unused.
*
* Depending on a configuration, all uses of such a thing may become
* #ifdef'ed away. Marking it with UNUSED would give a warning in a
* compilation where it is indeed used, and not marking it at all
* would give a warning in a compilation where it is unused. In such
* a case, MAYBE_UNUSED is the appropriate annotation to use.
*/
#define MAYBE_UNUSED __attribute__((__unused__))
#include "compat/bswap.h"