[Rd] [not extremely urgent:] modifiying messages on overriding implicit S4 generics + intended maskings

[Peter Ruckdeschel]

Hi r-devels,

I am coming with an RFE which is probably not extremely
urgent, dealing with (optionally) modifiying messages
on overriding implicit S4 generics + intended maskings
according to some (optional) pkg-individual files.

Details are shown below.

Any comments welcome,

Best, Peter

=============================
An aside right away:

For functions with many arguments, would it
be a bad idea to propose to make the implicit
S4 generic dispatch on less arguments (say the
first 2-3)?
=============================

DETAILS:

%------------------------------------------------
Overriding default S4 generic
%------------------------------------------------

In our distr-family of packages, we are about
to write S4 methods for qqplot for several
(mostly distribution-type) signatures.

In order to avoid to have to dispatch on too many
arguments, we would like to use the following generic

  setGeneric("qqplot", function(x, y, ...) standardGeneric("qqplot"))

while we would register the original qqplot function from
package stats as

  setMethod("qqplot", signature(x="ANY",y="ANY"), function(x, y,
    plot.it = TRUE, xlab = deparse(substitute(x)),
    ylab = deparse(substitute(y)), ...){

      mc <- match.call(call = sys.call(sys.parent(1)))
      if(missing(xlab)) mc$xlab <- xlab
      if(missing(ylab)) mc$ylab <- ylab
      mcl <- as.list(mc)[-1]
      return(invisible(
        do.call(stats::qqplot, args=mcl)))
    })

which should behave exactly the same as the original
stats function when called as usual.

Now doing so, on installing and building our package,
the following message is displayed:

  Creating a generic for "qqplot" in package  "distr"
     (the supplied definition differs from and overrides
      the implicit  generic in package "stats": Formal
      arguments differ: (x, y, ...), (x, y, plot.it,
      xlab, ylab, ...))

I would not bother too much about this message
(which /is/ a useful information for the package
developer anyway!), but it might irritate some users
to see this.

%------------------------------------------------
intended maskings
%------------------------------------------------

For similar reasons, in our packages we intentionally
mask some (few!) functions from packages stats and base.

In each case, we try to retain their original behaviour
when called as usual (and, AFAICS, they do so), and
also document this masking in corresponding files
MASKING in the inst/ folders.

Again, this masking gets automatically noticed as
a message on attaching the packages
(which again /is/ a useful information, anyway!).

%------------------------------------------------
proposed solution
%------------------------------------------------

So, for avoiding/modifying these automatic messages
on building/installing/attaching a package, could we
have optional parsable ASCII files, say

    INT_MASKING,   INT_OVERR_IMPL_GENERICS

(INT for /int/entional)
or, equally well, something shorter:-) in the inst
folder of a package, which are looked up and then
a correspondingly marked section would be
displayed instead of the original message?

A suggestion for the format of these files could
be:

Two blocks, each braced by some lines beginning
with "###":

+ the first one with a list of intentionally
  masked objects / overridden implicit generics,

+ the second one with a corresponding optional
  message to be displayed on build/install/attach
  instead of the original one (this second block
  could be left empty).

The format for the list in the first block could
be: one object a line, in form <pkgname>::<objname>.

In addition lines beginning with ";" would be
ignored (used as comment lines).

Example:

### begin object list
stats::qqplot
stats::df
### end object list
### begin displayed message
We intentionally mask stats functions qqplot and df,
because we have particular methods for them for
distribution-type arguments
### end displayed message

Now, each object mentioned in the first block, would no
longer be displayed within the default message on
build/install/attach (while masked objects / overridden implicit
generics remaining unmatched still do get displayed this
way).
In addition, unless the section in the corresponding
second block is empty, this section would be displayed
after the (again possibly empty) default message,
perhaps prepended by a title like "Intentional Masking"
respectively "Intentionally overridden implicit
generics".