R help - Feb 2003 - Rcmd check does not recognize formal generic function as code object

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?

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

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

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

At 04:16 PM 19/02/2003, Robert Gentleman wrote:
>   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).
Actually methods are also treated as non-entities, unless they are actually 
assigned into a function name, which the setMethod function does not do in 
itself nor require. This seems wrong - it should definitely be considered a 
mistake to define a new method using setMethod and not document it. Such 
documentation cannot occur in the .Rd file belonging to the class that it 
operates on if that class is defined in a different package.

Classes defined using setClass are similarly treated an non-entities. It 
seems that rcmd check is largely "unaware" of formal methods and
classes.

Regards
Gordon