[Rd] Documentation for S3 generics

[Gabor Grothendieck]

If you are writing the generic then you could use the same .Rd
file to list and document the methods or just mention them in the
text.   If the generic is not part of your package you could use the
-class.Rd file to do that or you could have separate .Rd pages for
specific methods.  I don't think its really standardized.

In zoo many of the methods are obvious and are just listed in the
text of the zoo.Rd page.  Others have their own .Rd file.

On 8/7/06, Gorjanc Gregor <Gregor.Gorjanc at bfro.uni-lj.si> wrote:
> 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
> >
>
>
>
>