changing function signatures and no library version # => must use too-general test

[Drew Adams]

You've heard this before, so those who might in fact be able to do something
about it will no doubt skip reading this, but...

Claim: A priori, it's good to avoid changing Emacs function signatures
(especially gratuitous changes), even if you think of the function as being
internal-only. Why? Because external Emacs libraries might try to use the
function across multiple Emacs versions. In Emacs, there is nothing that is
really "internal-only" in the sense that people will not see it and use it;
there are only different degrees of support by Emacs developers for external
use.

Yes, I know the mantra: You don't care about backward compatibility or
supporting multiple Emacs versions. But I do, and so do other
user-developers. Why send this to emacs-devel? Because in some cases there
is no reason not to be courteous to external users; that is, in some cases
it doesn't cost you anything to treat Emacs source code as if it will be
used by users.

Here's a simple problem: I have a library that uses function
`help-insert-xref-button'. Is it internal-only? I don't know, and I don't
really care. It has a nice doc string anyway, and it does just what I want,
so I use it.

Well, it turns out that the signature of this function changed fundamentally
from Emacs 21 to Emacs 22. Instead of just creating a new, different
function (whose existence could be tested with `fboundp'), which would have
been clean, some Emacs developer decided to keep the same function name and
completely change the parameter list. That's my complaint, in a nutshell -
that's NOT TRT, IMO.

It turns out that I can live without Emacs 21 support in this particular
case, so I need to test for the Emacs version in order to not use the wrong
function definition. Test for the Emacs version? Why don't I test for
something more specific? Good question.

There is no good way to test for the function with the right signature,
AFAIK. In Emacs 22 I could use `subr-arity' to test the number of args,
which would work in this case but not in cases where the number was the same
but the parameter types were different or their order changed - and, anyway,
that would require testing whether `subr-arity' is defined, and, if not, it
would require a different test (for Emacs other than 22).

There is no way to test for the particular version of the library that
defines the function. In this case, that is not a problem, because this and
related functions in fact moved from help.el to the new library
help-mode.el, so I can just test for (featurep 'help-mode). But in the more
general case, this is a problem: most Emacs libraries have no library
version.

In sum, it would be great if the following were true (in decreasing order of
desirability):

1. Emacs developers avoid changing function signatures or try to make such
changes compatible (e.g. via &optional). At least when other things are
equal. At the very least, avoid gratuitous changes. Rename a function if it
is not a user command and the signature is incompatibly different. Create an
alias to the old name and behavior, where feasible.

2. There is some way to test the signature of a function: number of args and
their types. The latter is no doubt unfeasible, given that Emacs Lisp is
generally untyped. The only notion of types we have in many cases is what
the doc string tells us. I mention this only as something that would be
desirable, not feasible.

3. Individual Emacs libraries have version numbers that can be tested.

Yes, I try to always use a test such as `fboundp' or `boundp', instead of an
Emacs version test or a `featurep' test. But in some cases, such as this
one, a too-general test seems unavoidable.