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

[Gordon Smyth]

Thanks ... there are issues here that I don't understand but your mention 
of promptClass prompted me to try promptMethods, and that seems to be the 
solution. The following files do the job and pass rcmd path without warnings:

test.R as before

myGenericFun.Rd replaced with

------------------------------------------------------
\name{myGenericFun-methods}
\alias{myGenericFun-methods}
\alias{myGenericFun,ANY-method}
\alias{myGenericFun,matrix-method}
\docType{methods}

\title{Methods for Function myGenericFun in package test}

\section{Methods}{\describe{
         \item{object = ANY}{default method}
         \item{object = matrix}{special method for matrices}
}}

\description{A trivial example}

\examples{
x <- rnorm(10)
myGenericFun(x)
dim(x) <- c(5,2)  # x is now a matrix
myGenericFun(x)
}

\keyword{methods}
\keyword{models}
-------------------------------------------------------

Regards
Gordon

At 04:16 PM 19/02/2003, you wrote:
>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   |
>+---------------------------------------------------------------------------+