Hi Drew.
My thinking was very localized to just this example, but i'll explain how I understand it and why i think it is the way to go.
In the display-completions-list, the function can take two arguments. There is a declare statement that says it should only take 1 argument. My understanding is that this is a change to the function signature, and that in the future the optional argument will be removed. Thus consumers of the display-completions-list *should get a warning*. People writing code that target this should adapt to the new way of doing this, as should other calls from inside of the core.
However, inside of the actual function display-completions-list, we still maintain legacy behavior until at some point we remove the functionality, after enough time that others have been able to see warnings and fix their own code. The idea is that the warning lets others know of an api change and update.
So my thinking was that the recursive call should not generate a warning since we are only hitting the old two argument function call when somewhere else has called with the old style. Presumably, the external call saw the warning and will update their convention. My understanding is that this function is generating a warning because it still handles the outdated way to call this code.
My idea of a solution (in broad terms here, with no concrete implementation yet) was to make sure that handling the antiquated calling from outside did not itself generate a warning. So the idea was that all calls to the old style of two arguments generate a warning unless they are called from within the original defun of display-completions-list. It seems like a duplicated error, as whoever originally called in could see that it should only take one argument, but for a period we still support this older behavior. The line inside of this function is:
(declare (advertised-calling-convention (completions) "24.4"))
So when the byte compiler sees a call that violates this advertised-calling-convention, generate a warning *unless* it is inside of the function where this declaration is found.
I agree with you that drowning in a sea of worthless warnings is bad, and that's why I want to fix them. This is a worthless warning precisely because, in a way, this recursive call outranks the warning. It ensures non-compliant code still works until the optional argument is removed. The reason that its important because its in the core is that this error is generated when compiling emacs.
In this case, 3rd parties are given information about how to not generate warnings: this warning is to only call display-completions-list with a single argument. Once this is followed, the warnings cease.