[Rd] Documentation for S3 generics

[Martin Maechler]

>>>>> "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

You can read more about all this in the "Writing R Extensions" manual.

Regards,
Martin