Eric Sunshine <sunshine@xxxxxxxxxxxxxx> 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@xxxxxxxx>
>> ---
>> 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.
