[Rd] Documentation for S3 generics
Gabor Grothendieck
ggrothendieck at gmail.com
Mon Aug 7 14:07:58 CEST 2006
Exporting a method allows the user to access the method directly
as opposed to calling the generic.
For example, try:
methods(plot)
The methods listed with stars are not exported although they are
still available through the generic. For example:
plot(ts(1:10))
plot.ts(ts(1:10))
both work but
plot(table(1:10)) # ok
plot.table(table(1:10)) # error
graphics:::plot.table(table(1:10)) # if you really must
On 8/7/06, Gorjanc Gregor <Gregor.Gorjanc at bfro.uni-lj.si> wrote:
> From: Martin Maechler [mailto:maechler at stat.math.ethz.ch]
> >>>>> "Gorjanc" == Gorjanc Gregor <Gregor.Gorjanc at bfro.uni-lj.si>
> >>>>> on Mon, 7 Aug 2006 11:59:31 +0200 writes:
>
> Gorjanc> Hello!
> Gorjanc> Say I have
>
> Gorjanc> myMethod <- function(x, ...)
> Gorjanc> UseMethod("myMethod")
>
> Gorjanc> myMethod.classA <- function(x, ...)
> Gorjanc> ...
>
> Gorjanc> myMethod.classB <- function(x, ...)
> Gorjanc> ...
>
> Gorjanc> myMethod.classC <- function(x, arg2, ...)
> Gorjanc> ...
>
> Gorjanc> and I would like to properly document these as generics. Then I have to
> Gorjanc> use in usage section
>
> Gorjanc> \method{myMethod}{classA}(x, ...)
> Gorjanc> \method{myMethod}{classB}(x, ...)
> Gorjanc> \method{myMethod}{classC}(x, arg2, ...)
>
> Gorjanc> But is it really necessary to have the same documentation for myMethod.classA
> Gorjanc> and myMethod.classB?
>
> > If you do export the methods from your package by
> > either
> > - not using NAMESPACE or
> > - exporting them explicitly in NAMESPACE,
> >
> > then you have to document them.
> >
> > Most newer "good" R packages use NAMESPACE though,
> > and the convention is to export only those S3 methods that have
> > ``surprising arguments''
> >
> > i.e., arguments that are not part of the generic
> > (where all the generic's arguments are documented).
> >
> > For your situation:
> >
> > 1) use <pkg>/NAMESPACE
> > 2) only export myMethod.classC \ because only that
> > 3) only document myMethod.classC / method has surprising arguments
> >
>
> Huh, I hoped for a more "generic" answer. My situation is not "so simple"
> as described above as I have
>
> myMethod.classA <- function(x, arg1, arg2, ...)
> ...
>
> myMethod.classB <- function(x, arg1, arg2, ...)
> ...
>
> myMethod.classC <- function(x, arg1, arg2, arg3...)
>
> And yes I do use NAMESPACE and I export all methods explicitely. You
> are saying that there is no need to export methods that do not have
> ``surprising arguments'', but how can a user use them if they are not
> exported --> so method dispatch can access methods that are not
> exported?
>
> Are you still recommending 1), 2) and 3) above?
>
> Thank you very much!
>
> Gregor
>
> ______________________________________________
> R-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
More information about the R-devel
mailing list