Rcmd check does not recognize formal generic function as code object

On Wed, Feb 19, 2003 at 03:44:31PM +1100, Gordon Smyth wrote:

Dear all,

I am trying to write a package using formal methods and classes from the
methods package. I have not been able to get the package to pass rcmd 

check

without warnings, because rcmd check does not recognize my generic
functions as code objects and therefore queries why they have 

documentation

entries.

I have isolated the problem in a very small trivial example which I give
below. I have one file test.R in the R directory and one file test.Rd in
the man directory. Here is the message from rcmd check:

    * checking for code/documentation mismatches ... WARNING
    Objects with usage in documentation object 'myGenericFun' but missing
from code:
    [1] "myGenericFun"

Can I get rcmd check to recognize that myGenericFun is something that need
a documentation entry?

  Mostly this is not documented (yet) because the exact API is still
  being worked on.

  Documenting generic functions (and the methods that they dispatch)
  is hard in a language that allows users to attach and detach
  packages (and hence both generic functions and methods). We don't
  really have the notion of dynamic documentation (yet) that will
  handle the applications that are likely to arise.

  The current problem arises, I think, from an effort to solve a
  different problem. Since many functions in "base" are not generic
  (yet?) when a package author wants to make one generic we don't
  really want to override the documentation for that function in base
  ( we might want to document the method that we are adding, but the
  creation of the generic is artificial in some sense, if users could
  assign into base, or if all base functions were generic the generic
  would live in base and be documented there).

  It was decided that should not be an error to omit documentation for
  a generic function defined in a package (whose sole purpose is to
  extend a current function to be generic). It appears that the
  implementation of that decision was to treat all generic functions
  in packages as non-entities. That is probably not the best and one
  can argue that there should be no warning if a generic is documented
  (nor one if it isn't and there is already documentation for it
  somewhere).

  What we have been doing is using promptClass and documenting methods
  (and generics with the classes) in Bioconductor.

  This will continue to change as we gain experience with the methods
  class and with feedback from users. As I noted, with generic
  functions it would be nice to explain the purpose and list all
  available methods when the user wants help.

 I think that you can safely ignore this warning.

 Robert

The document "Writing R Extensions" doesn't cover formal methods and
classes, and I haven't found any other documentation that covers writing
packages using formal methods. I am working from looking at code in
Bioconductor, pixmap and gpclib. I downloaded source for pixmap and
confirmed that it has the same problem with rcmd check that I mention here.

Any advice gratefully received, including any tips about how to write
organise .Rd files for generic methods.

Thanks
Gordon

-------------------------------- test.R -----------------------------
.initClassesandMethods <- function(where) {
setGeneric("myGenericFun",where=where,
         def=function(object) standardGeneric("myGenericFun"))
setMethod("myGenericFun","ANY",where=where,
         def=function(object) paste("myGenericFun on object of
class",class(object)))
setMethod("myGenericFun","matrix",where=where,
         def=function(object) "myGenericFun for matrices")
}
#  Use of .First.lib ensures that the new generic function is assigned in
the package itself
.First.lib <- function(libname, pkgname) {
         require(methods, quietly=TRUE)
#  Find what position in the search path this package is
         where <- match(paste("package:", pkgname, sep=""), search())
         .initClassesandMethods(where)
         cacheMetaData(as.environment(where))
}
------------------------- end test.R ----------------------------------

------------------------- myGenericFun.Rd ------------------------
\name{myGenericFun}
\docType{methods}
\alias{myGenericFun}
\title{My Generic Function}
\description{A simple example generic function.}

\usage{myGenericFun(object)}

\arguments{
   \item{object}{Any R object. A special method exists for objects of 

class

"matrix".}
}

\value{A character string explaining the class of object and the method
dispatched.}

\examples{
x <- rnorm(10)
myGenericFun(x)
dim(x) <- c(5,2)
myGenericFun(x)
}

\keyword{models}
-------------------------------- end myGenericFun.Rd -------------------

---------------------------------------------------------------------------------------

Dr Gordon K Smyth, Senior Research Scientist, Bioinformatics,
Walter and Eliza Hall Institute of Medical Research,
1G Royal Parade, Parkville, Vic 3050, Australia
Tel: (03) 9345 2326, Fax (03) 9347 0852,
Email: smyth at wehi.edu.au, www: http://www.statsci.org

--
+---------------------------------------------------------------------------+
| Robert Gentleman                 phone : (617) 632-5250                   |
| Associate Professor              fax:   (617)  632-2444                   |
| Department of Biostatistics      office: M1B20                            |
| Harvard School of Public Health  email: rgentlem at jimmy.dfci.harvard.edu   |
+---------------------------------------------------------------------------+