[R-pkg-devel] Documenting courtesy S3 methods

[Lenth, Russell V]

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