# [Bioc-devel] documentation help

Finak, Greg gfinak at fhcrc.org
Wed Mar 9 16:02:49 CET 2011

Hi, Stefano

The way I handle this is to write the generic as you did..
> setGeneric("gcNorm", function(object, ...){standardGeneric("gcNorm")})
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:

> 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
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel