Difference between the def and useAsDefault parameters of setGeneric - r

Question

In the S4 setGeneric function documentation, the difference between the def and useAsDefault parameters is poorly explained: they seem to do the same thing, but in practice there's a confusing and poorly contextualised explanation. Could anybody provide a practical example where the two entries behave differently?

Answer 1

Some context
For better or worse, the behaviour of setGeneric differs in quite subtle ways depending on its arguments. It is possible that some of these quirks are not intentional. The help page accessed by ?setGeneric and even the reference book Extending R (Chambers, 2016) follow the Pareto principle by spelling out the most frequent use cases and only sketching out the less frequent ones, in particular not expounding about useAsDefault whose use is intended only for nonstandard generic functions.
S4 generic functions are designated by the formal class genericFunction, which has three direct subclasses: standardGeneric, nonstandardGenericFunction, and groupGenericFunction. To give context to the behaviour of setGeneric, we should distinguish between standard and nonstandard generic functions. (Group generic functions are defined by setGroupGeneric, not setGeneric, so we ignore them here.)
Standard generic functions only perform method dispatch: arguments are passed "as is" to the dispatched method, and the return value of the method is returned "as is" by the generic. Nonstandard generic functions perform method dispatch while allowing for pre-processing of arguments and post-processing of return values.
Hence if we define a generic function with setGeneric("zzz", def=), then in the standard case body(zzz) is just the call standardGeneric("zzz"), whereas in the nonstandard case it is a call containing the call standardGeneric("zzz"), typically of the form:
{
## optionally do some stuff with the arguments
val <- standardGeneric("zzz")
## optionally do some stuff with 'val', then return
}
To answer your question, let's restrict attention to calls to setGeneric of the form
setGeneric("zzz", def=, useAsDefault=)
where def is a function and useAsDefault is either a function or missing, and let's further assume that there is no existing function zzz.
Then setGeneric behaves in one of three ways, depending on body(def):
If body(def) does not contain the call standardGeneric("zzz"),
then setGeneric constructs a standard generic function and assigns
it to the symbol zzz in the calling environment. It associates
with zzz a default method (of formal class derivedDefaultMethod),
which is retrieved as zzz#default. The default method
is useAsDefault if not missing and def otherwise.
setGeneric("zzz", def = function(x, ...) 1 + x, useAsDefault = function(x, ...) x)
## [1] "zzz"
zzz
## standardGeneric for "zzz" defined from package ".GlobalEnv"
##
## function (x, ...)
## standardGeneric("zzz")
## <environment: 0x14f048860>
## Methods may be defined for arguments: x
## Use showMethods(zzz) for currently available ones.
zzz#default
## Method Definition (Class "derivedDefaultMethod"):
##
## function (x, ...)
## x
##
## Signatures:
## x
## target "ANY"
## defined "ANY"
zzz(0)
## [1] 0
If body(def) is precisely the call standardGeneric("zzz"),
then, as in Case 1, setGeneric constructs and assigns to zzz
a standard generic function. However, here, the default method
is determined entirely by useAsDefault.
If useAsDefault is missing, then zzz gets no default method.
setGeneric("zzz", def = function(x, ...) standardGeneric("zzz"))
## [1] "zzz"
zzz
## standardGeneric for "zzz" defined from package ".GlobalEnv"
##
## function (x, ...)
## standardGeneric("zzz")
## <environment: 0x112010f60>
## Methods may be defined for arguments: x
## Use showMethods(zzz) for currently available ones.
zzz#default
## NULL
zzz(0)
## Error in (function (classes, fdef, mtable) :
## unable to find an inherited method for function 'zzz' for signature '"numeric"'
If body(def) is not precisely the call standardGeneric("zzz"),
but does contain it, then setGeneric constructs and assigns to
zzz a nonstandard generic function. As in Case 2, useAsDefault
specifies the default method. However, here, the generic function
inherits its body from def.
setGeneric("zzz", def = function(x, ...) 1 + standardGeneric("zzz"), useAsDefault = function(x, ...) x)
## [1] "zzz"
zzz
## nonstandardGenericFunction for "zzz" defined from package ".GlobalEnv"
##
## function (x, ...)
## 1 + standardGeneric("zzz")
## <environment: 0x123fd5410>
## Methods may be defined for arguments: x
## Use showMethods(zzz) for currently available ones.
zzz#default
## Method Definition (Class "derivedDefaultMethod"):
##
## function (x, ...)
## x
##
## Signatures:
## x
## target "ANY"
## defined "ANY"
zzz(0)
## [1] 1