RE: Arbitrary function: find the number(s) of expected arguments

[Drew Adams <drew.adams@oracle.com>]

>  `subr-arity' is still in the documentation, but I replaced its
> description with an advice to use `func-arity' instead.

Again, that is wrong, IMO.

IIUC, you _cannot_ use `func-arity' to test whether something
is a subr.  You can use `subr_arity' to give you the arity of
a subr AND to raise an error if the argument is not a subr.
The latter behavior is not available in `func-arity'.

The proper doc for `subr-arity' is to say what it _does_,
including that it raises an error for non-subr arg.  Its doc
can, and should, refer to `func-arity', but only as a way to
test the arity of _any_ function - not as a recommended
replacement for `subr-arity'.

IOW, I am repeating the same argument I made before, when
I said that `subr-arity' should not be deprecated and
simply replaced by `func-arity'.

If my argument is being rejected (in effect - in the new doc
string) then why are we not doing that openly (deprecating
`subr-arity' and replacing it with `func-arity')?

Either `func-arity' is a proper replacement for `subr-arity'
or it is not.  (I think it is not.)  If it is, then replace
it properly.

In addition, the new doc string for `subr-arity' also suffers
from making readers work extra hard.  They need to refer to
the doc of `func-arity', not only for the general description
of the behavior and each of the parameters, but also to
understand the difference wrt symbol indirection.

This is a step backward.  Unless we are really deprecating
and replacing it, we should document `subr-arity' properly,
as before, with the addition of cross-ref to see `func-arity',
stating that it handles any type of function.

IOW, if you want the arity of an arbitrary function, you can
use `func-arity' to get that.  That's all.