Skip to content

[Bioc-devel] documentation help

4 messages · Greg Finak, Stefano Berri, Martin Morgan

Original
Stefano Berri
# 
Hi.

I want a method that requires an object (obviously) and allows *optional*
arguments

so I set it up like this

setGeneric("gcNorm", function(object, ...){standardGeneric("gcNorm")})

then I started the documentation and wanted to document the optional
arguments

\usage{
gcNorm(object, ...)
}

\arguments{
gcNorm(object, excludeFromGCNorm = character(0), maxNumPoints = 10000, ...)
\item{object}{An object of Class \code{"CNAnorm"}}
\item ...
\item ...
}

but, while running R CMD CHECK I get this warnings

+++++++++++++++++++++++++++++

* checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'gcNorm'
  ...
Documented arguments not in \usage in documentation object 'gcNorm':
  excludeFromGCNorm maxNumPoints

Functions with \usage entries need to have the appropriate \alias entries,
and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.
+++++++++++++++++++++++++++++

An option could be to add the optional arguments in the definition

setGeneric("gcNorm", function(object, excludeFromGCNorm, maxNumPoints) ... )

but then I guess it looks like I always have to pass them and are not
optional anymore...

what am I not getting right? What is the way to go?

Thanks for your help

Stefano
Greg Finak
# 
Hi, Stefano

The way I handle this is to write the generic as you did..
Then have an S4 method defined as that takes the various optional arguments but dispatches on the generic signature..

setMethod("gcNorm",signature=c("objtype"), function(obj,optarg1,optarg2=,...){
#function definition
})

The method above is called when you pass an object of type "objtype" to gcNorm, and takes additional arguments optarg1, and optarg2


To document this, you'd have the following

\name{gcNorm}
\alias{gcNorm}
\alias{gcNorm-methods}
\alias{gcNorm,objtype-method}

\usage{
\S4method{gcNorm}{objtype}(obj,optarg1,optarg2,...)
}

\arguments{
\item{obj}{
}
\item{optarg1}{
}
\item{optarg2}{
}
\item{...}{
}
}
The main thing is that inside the usage tag you enclose the usage with \S4method which allows you to include the optional arguments. If they have default values, you would include them here, since the usage must match the function definition.

You could write other S4 methods that take different types of obj and other optional arguments and document them in the same file.

The aliases tell R's documentation system that this Rd file documents the gcNorm function as well as gcNorm methods and which gcNorm methods specifically (there's probably a more technical interpretation of this.. but it's how I think of it).

Cheers

Greg Finak

Sent from my iPhone
On 2011-03-09, at 4:27 AM, "Stefano Berri" <S.Berri at leeds.ac.uk> wrote:

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Stefano Berri
    

    

      
      #
    

  


  

      
Hi Greg

Thanks a lot for your help.
I think I am almost there, still have a warnings I cannot solve

Documentation file
+++++++++++++++++++++
\name{gcNorm}
\docType{methods}
\alias{gcNorm}
\alias{CNAnorm}
\alias{gcNorm-methods}
\alias{gcNorm, CNAnorm-method}

....

\usage{
\S4method{gcNorm}{CNAnorm}(object, excludeFromGCNorm = character(0),
     maxNumPoints = 10000)
} 

...

++++++++++++++++++++++

code

++++++++++++++++++++++

setGeneric("gcNorm", function(object, ...){standardGeneric("gcNorm")})

setMethod(f = "gcNorm", signature = "CNAnorm", definition = .gcNorm)

.gcNorm <- function(object, excludeFromGCNorm = character(0), maxNumPoints =
10000){
# all the code
}

++++++++++++++++++++++

running R CMD CHECK

* checking Rd \usage sections ... WARNING
Objects in \usage without \alias in documentation object 'gcNorm':
  \S4method{gcNorm}{CNAnorm}

Functions with \usage entries need to have the appropriate \alias entries,
and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.


Any help is really appreciated

thanks

Stefano

  
  


  


      

    

    

      
      

        


  

        

      Martin Morgan
    

    

      
      #
    

  


  

      
On 03/09/2011 08:21 AM, Stefano Berri wrote:

            

      
      
      
    

        
Hi Stefano --

no ' ' between 'gcNorm,' and 'CNAnorm'.

Martin