[Rd] Strange, most probably unjustified, codoc mismatch for S4 method with one argument plus '...' (re-try)

[Martin Morgan]

On 12/14/2012 09:46 AM, Ulrich Bodenhofer wrote:
> Hi,
>
> I just figured out that I accidentally posted my message in HTML, so I am
> retrying in plain text only. Sorry.
>
> I am currently extending one of our CRAN packages and ran into an unexpected
> problem when checking the source package. I got some warnings in the step "*
> checking for code/documentation mismatches". I double checked everything and did
> not see anything that would actually justify this warning. After testing around
> for quite a while, I think I can now pinpoint the problem. In order to make
> myself clear, I need to explain the situation in more detail:
>
> The default method (passed as def argument of setGeneric()) has the formal
> argument list (x, y, ...). Suppose I want to register a method with a signature
> without y, say signature(x="matrix", y="missing"). If I pass a function to
> setMethod() that only has the argument x,i.e. function(x) {...}, everything
> works well. It also works well if I register a function with additional
> arguments, e.g. function(x, dummy=NULL, ...){...} (note: y is missing in the
> definition). However, if I try to register a function with two formal arguments,
> x and '...', i.e.function(x, ...){...}, I get the warning that argument y is
> present in the code but missing in the documentation , although it is actually
> NOT in the code. In order to make this reproducible for everybody, I put
> together a little dummy package in which one of the methods leads to exactly
> this warning:
>
>     http://www.bioinf.jku.at/people/bodenhofer/codocMismatchTest_0.0.1.tar.gz
>
> Just run 'R CMD check' on this archive and you'll see. You will also see from
> the code and the corresponding documentation that the warning seems unjustified.
> I tried the following R versions: 2.12.1, 2.13.0, 2.13.1, 2.14.0, 2.14.1,
> 2.15.0, 2.15.1, 2.15.2, 2.16.0 (devel), and all consistently gave the same warning.
>
> Is this a bug or is there a special reason for this behavior? Any help is
> gratefully appreciated!

In ?setMethod there is this paragraph

      It is possible to have some differences between the formal
      arguments to a method supplied to 'setMethod' and those of the
      generic. Roughly, if the generic has ... as one of its arguments,
      then the method may have extra formal arguments, which will be
      matched from the arguments matching ... in the call to 'f'.  (What

and in practice the expectation is that if a generic has formals x, y, and ..., 
then a method will have formals x, y, and possibly additional arguments. None of 
these methods follow this

setMethod("dummyMethod", signature(x="matrix", y="missing"),
           function(x) {})

setMethod("dummyMethod", signature(x="matrix", y="missing"),
           function(x) {})

setMethod("dummyMethod", signature(x="data.frame", y="missing"),
           function(x, ...) {})

each should have been written as, for instance

     setMethod("dummyMethod", signature(x="matrix", y="missing"),
               function(x, y, ...) {})

The reason for the codoc warning stems from how R represents methods with 
signatures different from their generic, typically when _additional_ arguments 
are used,

      (what
      actually happens is that a local function is created inside the
      method, with the modified formal arguments, and the method is
      re-defined to call that local function.)

So e.g.,

> selectMethod(dummyMethod, c("matrix", "missing"))
Method Definition:

function (x, y, ...)
{
     .local <- function (x)
     {
     }
     .local(x, ...)
}

Signatures:
         x        y
target  "matrix" "missing"
defined "matrix" "missing"

and hence the codoc warning

* checking for code/documentation mismatches ... WARNING
Codoc mismatches from documentation object 'dummyMethod':
\S4method{dummyMethod}{data.frame,missing}
   Code: function(x, y, ...)
   Docs: function(x, ...)
   Argument names in code not in docs:
     y
   Mismatches in argument names:
     Position: 2 Code: y Docs: ...

Your other setMethod

also results in code that likely differs from your expectation, e.g., no 
argument matching by position

     setMethod("dummyMethod", signature(x="list", y="missing"),
               function(x, sel=NULL, ...) {})

 > selectMethod(dummyMethod, signature(x="list", y="missing"))
Method Definition:

function (x, y, ...)
{
     .local <- function (x, sel = NULL, ...)
     {
     }
     .local(x, ...)
}

Signatures:
         x      y
target  "list" "missing"
defined "list" "missing"

Hope that helps,

Martin

 >
>
> Thanks in advance and best regards,
> Ulrich
>
>
> ------------------------------------------------------------------------
> *Dr. Ulrich Bodenhofer*
> Associate Professor
> Institute of Bioinformatics
>
> *Johannes Kepler University*
> Altenberger Str. 69
> 4040 Linz, Austria
>
> Tel. +43 732 2468 4526
> Fax +43 732 2468 4539
> bodenhofer at bioinf.jku.at <mailto:bodenhofer at bioinf.jku.at>
> http://www.bioinf.jku.at/ <http://www.bioinf.jku.at>
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel


-- 
Computational Biology / Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N.
PO Box 19024 Seattle, WA 98109

Location: Arnold Building M1 B861
Phone: (206) 667-2793