[Rd] R CMD CHECK WARNING inappropriate for S4 method?

[John Chambers]

This one is subtle, and has mostly to do with namespace and imports, 
only secondarily to do with methods.  Bear with a fairly long story.

The description below is for a simple package P1 that imitates the 
pattern of imports in GSEABase.

First, what's generating the warning?  The function undoc() in the tools 
package looks for all the methods defined in the current package, for 
"union" in this case.  In r-devel, that uses the function findMethods().

What it gets is:
 > names(findMethods("union", where = 2))
[1] "ANY#ANY"             "graph#graph"         "testClass#testClass"

(where "testClass" is the new class that P1 is adding.)

What it "normally" gets in these circumstances is:
 > names(findMethods("union", where = 2))
[1] "testClass#testClass"

In the first case, undoc() naturally assumes you created all the methods 
and wants you to document them.

The question, then, is why are you getting the extra methods?

The answer, to the extent I understand it, is that P1 (and GSEABase) 
used the
  Imports:graph
directive in the DESCRIPTION file, instead of explicitly doing the 
import() commands in the NAMESPACE file.  Just what this does 
differently  I'm not sure, but the effect is that the generic version of 
union() in the "graph" package is no longer in the imports environment 
for package P1:

 > n1 = asNamespace("P1")
 > objects(parent.env(n1), all=TRUE, pattern="union")
character(0)

The result is that P1 owns the union() generic and all its methods.  In 
particular, a generic function "union" is created in P1.

The alternative way to specify the imports is to use the NAMESPACE file, 
say with:

import(graph)

Package "graph" must be added to the Depends: line of the DESCRIPTION 
file, instead of being in the Imports: line.  (Otherwise, you still get 
the new generic, owning all the methods.)

Now the generic version of union() is in the imports environment for P1; 
the setMethod() call in P1 does not create a new generic.  We can see 
this by:
 > n1 = asNamespace("P1")
 > objects(parent.env(n1), all=TRUE, pattern="union")
[1] ".__M__union:base" ".__T__union:base" "union"          


One final catch: In this version, you do need to ensure that the user's 
call to union() sees the generic version at run time, and not the 
nongeneric version in base.  Either require(graph) or, in P1's NAMESPACE:

export(union)

Perhaps needless to say, this is all a bit more subtle than one would like.

John





Martin Morgan wrote:
> The package 'graph' defines classes graph and graphNEL (extending
> graph) and a union,graph,graph-method. These are all exported and
> fully documented.
>
> The package 'GSEABase' Imports: graph and importClassesFrom(graph,
> graphNEL). GSEABase defines methods on union for its own classes (not
> graph / graphNEL), and has exportMethods(union).
> union,graph,graph-method is not used in GSEABase.
>
> R version 2.8.0 Under development (unstable) (2008-06-08 r45879)
> reports from R CMD CHECK GSEABase
>
> * checking for missing documentation entries ... WARNING
> Undocumented S4 methods:
>   generic 'union' and siglist 'graph,graph'
>
> I guess union,graph,graph-method is exposed to the user indirectly by
> its import along with the graph class and export along with the
> newly-defined union methods.
>
> It would seem inappropriate to document union,graph,graph-method in
> GSEABase. Making GSEABase Depend: graph rather than Import: graph does
> not help.
>
> Any guidance welcome.
>
> Thanks,
>
> Martin
>