[R-pkg-devel] Documenting courtesy S3 methods

[Bert Gunter]

From WRE:

"As from R 3.6.0 one can also use S3method() directives to perform
*delayed*registration.
With

if(getRversion() >= "3.6.0") {
    S3method(pkg::gen, cls)
}

function gen.cls will get registered as an S3 method for class cls and
generic gen from package pkg only when the namespace of pkg is loaded. This
can be employed to deal with situations where the method is not
“immediately” needed, and having to pre-load the namespace of pkg (and all
its strong dependencies) in order to perform immediate registration is
considered too onerous."

I understand the issue is documentation, but if you took this route, could
you not document your S3 method as usual without loading multcomp's (or
whatever) namespace. You could include a \note section in the doc saying
that the multcomp namespace must be explicitly loaded if your method is to
be used (perhaps showing the code to do so)

If I am clearly mistaken about this, feel free to dismiss without reply.


Cheers,
Bert Gunter

"The trouble with having an open mind is that people keep coming along and
sticking things into it."
-- Opus (aka Berkeley Breathed in his "Bloom County" comic strip )


On Wed, Aug 5, 2020 at 5:58 PM Lenth, Russell V <russell-lenth using uiowa.edu>
wrote:

> Dear package developers,
>
> My package offers a few methods whose generics are in other packages; for
> example, 'cld', for which the generic is in the 'multcomp' package. Unless
> the user wants to use cld() (which I don't even encourage), they do not
> need the multcomp package to use other features of my package. Therefore, I
> do not want to import and re-export multcomp::cld. Instead, on loading my
> package, I dynamically register the method via RegisterS3Method() if the
> user's system happens to have multcomp installed; and if they don't, then
> they can still use my package, just not the cld method. this has worked
> well and keeps down the number of dependencies.
>
> The problem is documenting it. I thought I had it solved by using this
> roxygen2 tag:
>
>     #' @method multcomp::cld emmGrid
>
> In turn, this tag generates these lines in the \usage section of my .Rd
> file:
>
>     \method{multcomp::cld}{emmGrid}(object, details = FALSE, sort = TRUE,
> by,
>       alpha = 0.05, Letters = c("1234567890", LETTERS, letters),
>       reversed = FALSE, ...)
>
> and the resulting help file looks like this:
>
>     ## S3 method for class 'emmGrid'
>     multcomp::cld(object, details = FALSE, sort = TRUE, by,
>       alpha = 0.05, Letters = c("1234567890", LETTERS, letters),
>       reversed = FALSE, ...)
>
> This is exactly what I want. It tells the user clearly that if they want
> to use cld(), they have to have multcomp installed, and either name it
> explicitly in the call or have it in the search path.
>
> No problems occur until I check the package, when I get this warning
> message:
>
>     Bad \usage lines found in documentation object 'summary.emmGrid':
>       <unescaped bksl>method{multcomp::cld}{emmGrid}(object, details =
> FALSE, sort = TRUE, by,
>         alpha = 0.05, Letters = c("1234567890", LETTERS, letters),
>         reversed = FALSE, ...)
>
> Well I suppose this is "bad" as in unexpected; but it seems to be not bad
> in that it doesn't keep the help page from formatting correctly. And truly,
> I don't see how it could cause any harm. At lest the usage comes out
> correctly in both the HTML help and the PDF manual.
>
> I can avoid the problem just by omitting "multcomp::". But then the user
> doesn't get such a clear message about how to use the function.
>
> I'm interested in suggestions, but again I would regard importing
> multcomp::cld as an unhelpful suggestion. We ought to be able to provide
> courtesy methods for generics in other packages (and this is not the only
> one in my package) without importing a whole bunch of unneeded stuff and
> doubling the number of required installations.
>
> Thanks
>
> Russ
>
> Russell V. Lenth  -  Professor Emeritus
> Department of Statistics and Actuarial Science
> The University of Iowa  -  Iowa City, IA 52242  USA
> Voice (319)335-0712 (Dept. office)  -  FAX (319)335-3017
>
> ______________________________________________
> R-package-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>

	[[alternative HTML version deleted]]