[Rd] Documentation for S3 generics

[Gorjanc Gregor]

Thank you Gabor for this explanation. No I get it! However,
I am still not clear on documenting generic methods in my case.
I could document only the methods that have more arguments than
simple ones, in my case classX, but then the output in help
page will only be for classC and I have to mention other classes
in the text. This is fine, but is for sure confusing for the reader
of help page.

Gregor


-----Original Message-----
From: Gabor Grothendieck [mailto:ggrothendieck at gmail.com]
Sent: Mon 2006-08-07 14:07
To: Gorjanc Gregor
Cc: Martin Maechler; r-devel at stat.math.ethz.ch
Subject: Re: [Rd] Documentation for S3 generics
 
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
>