[Rd] Documentation for S3 generics

[Gorjanc Gregor]

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