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@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
