R devel - Dec 2012 - Strange, most probably unjustified, codoc mismatch for S4 method with one argument plus '...' (re-try)

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!

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>

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