[R] Rcmd check does not recognize formal generic function as code object

[Robert Gentleman]

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
> 
> ______________________________________________
> R-help at stat.math.ethz.ch mailing list
> http://www.stat.math.ethz.ch/mailman/listinfo/r-help

-- 
+---------------------------------------------------------------------------+
| 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   |
+---------------------------------------------------------------------------+