[Roxygen-devel] documenting multiple methods for a generic S4 method

[Vinh Nguyen]

Dear list,

Suppose I define multiple S4 methods in my .R file. For example,

setGeneric("genF", function(fitobj, ...) standardGeneric("genF"))
setMethod("genF", signature(fitobj="lm"), function(fitobj){ print("lm") })
setMethod("genF", signature(fitobj="glm"), function(fitobj){ print("glm") })

If I run package.skeleton() on my workspace, I'll get a
genF-methods.Rd file in the man directory that appears to have
template to document both methods.

If I use roxygen and place "@name genF-methods" in the documentation,
then only one (the later one in the .R file) gets documented in the
genF-methods.R file; genF-methods gets written twice (so first
documentation is overwritten). How should we be documenting multiple
S4 methods with roxygen?

Thanks.
Vinh
--
Vinh Nguyen
Department of Statistics
Donald Bren School of ICS
2231 Bren Hall
University of California, Irvine
Irvine, CA 92607
vqnguyen at uci.edu | http://www.ics.uci.edu/~vqnguyen/
Schedule a meeting: http://tungle.me/VinhNguyen

[Manuel J. A. Eugster]

Hi Vinh,

the @rdname (only in Rd2) merges different documentations; so
setting

#' @rdname genF-methods

in front of every method should produce one Rd file with all
methods documented.


Manuel.

Post by Vinh Nguyen
Dear list,
Suppose I define multiple S4 methods in my .R file. For example,
setGeneric("genF", function(fitobj, ...) standardGeneric("genF"))
setMethod("genF", signature(fitobj="lm"), function(fitobj){ print("lm") })
setMethod("genF", signature(fitobj="glm"), function(fitobj){ print("glm") })
If I run package.skeleton() on my workspace, I'll get a
genF-methods.Rd file in the man directory that appears to have
template to document both methods.
then only one (the later one in the .R file) gets documented in the
genF-methods.R file; genF-methods gets written twice (so first
documentation is overwritten). How should we be documenting multiple
S4 methods with roxygen?
Thanks.
Vinh
--
Vinh Nguyen
Department of Statistics
Donald Bren School of ICS
2231 Bren Hall
University of California, Irvine
Irvine, CA 92607
vqnguyen at uci.edu | http://www.ics.uci.edu/~vqnguyen/
Schedule a meeting: http://tungle.me/VinhNguyen
_______________________________________________
Roxygen-devel mailing list
Roxygen-devel at lists.r-forge.r-project.org
https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel

[Vinh Nguyen]

Manuel:

When I turn on use.Rd2=TRUE in roxygenize(), I get an error with my S4
class definition:

##' An S4 class that stores inferential values of a fitted model object.
##'
##' An S4 class that inherits from the \code{matrix} class. Rows
##' correspond to different coefficients and columns consist of point
##' estimates (point.est), confidence intervals (ci.lo and ci.hi),
##' p-values (p.value), and sample size (n).
##'
##' @name inference-class
##' @slot .Data matrix consisting of inferential values
##' @slot sample.size Sample size used in model fit.
##' @slot robust.se Boolean indicator whether robust standard errors were
##' used.
##' @slot two.sided Boolean indicator whether p-values corresond to a
##' two-sided test or one-sided.
##' @slot ci.level Confidence level.
setClass(Class="inference"
, representation=representation(model="character"
, sample.size="numeric"
, robust.se="logical"
, two.sided="logical"
, ci.level="numeric")
, contains=c("matrix"))

Error:
Processing genF-methods: witten to inference/man/genF-methods.Rd
Processing genF,-method: witten to inference/man/genF,-method.Rd
Processing genF,-method: witten to inference/man/genF,-method.Rd
Processing inference-class
-class:Error in repr[[slots[[i]]$name]] :
attempt to select less than one element

No Rd files are generated due to the error. Do you see any error in
my documentation?

Also, I'm a little confused when it comes to @name, @rdname, and
@title for S4 methods documentation with roxygen. Should all three be
specified? Should they be identical for the generic definition and
for the particular methods with differing signatures? Some guidance
would be nice.

Thanks!

I think I'm near the point of just going the S3 route as S4 seems so
complicated in regards to documentation.

Vinh

[Vinh Nguyen]

Please disregard the following. Everything is resolved once I cleaned
up my ./man folder. Thanks!

Vinh

Post by Vinh Nguyen
When I turn on use.Rd2=TRUE in roxygenize(), I get an error with my S4
##' An S4 class that stores inferential values of a fitted model object.
##'
##' An S4 class that inherits from the \code{matrix} class. ?Rows
##' correspond to different coefficients and columns consist of point
##' estimates (point.est), confidence intervals (ci.lo and ci.hi),
##' p-values (p.value), and sample size (n).
##'
##' used.
##' two-sided test or one-sided.
setClass(Class="inference"
? ? ? ? , representation=representation(model="character"
? ? ? ? ? ? , sample.size="numeric"
? ? ? ? ? ? , robust.se="logical"
? ? ? ? ? ? , two.sided="logical"
? ? ? ? ? ? , ci.level="numeric")
? ? ? ? , contains=c("matrix"))
Processing genF-methods: witten to inference/man/genF-methods.Rd
Processing genF,-method: witten to inference/man/genF,-method.Rd
Processing genF,-method: witten to inference/man/genF,-method.Rd
Processing inference-class
?attempt to select less than one element
No Rd files are generated due to the error. ?Do you see any error in
my documentation?
@title for S4 methods documentation with roxygen. ?Should all three be
specified? ?Should they be identical for the generic definition and
for the particular methods with differing signatures? ?Some guidance
would be nice.
Thanks!
I think I'm near the point of just going the S3 route as S4 seems so
complicated in regards to documentation.
Vinh

[Vinh Nguyen]

Manuel wrote the following:

"
Hi Vinh,

the @rdname (only in Rd2) merges different documentations; so
setting

#' @rdname genF-methods

in front of every method should produce one Rd file with all
methods documented.


Manuel.
"

I've decided to write one documentation for a generic function, and
make use of aliases:

##' Inference for fitted model objects.
##'
##' Extract point estimates, standard errors, confidence intervals,
##' p-values, and sample size.
##' @rdname infer,-methods
##' @aliases infer infer,-method
##' @param fitobj Fitted model object, such as those of class \code{lm}.
##' @param vars Vector of variable names to obtain inference information
##' for. Defaults to \code{NULL} which corresponds to all variables
##' in the fitted model.
##' @param robust.se Boolean indicator for whether robust standard
##' errors should be use. Defaults to \code{TRUE}.
##' @param two.sided Boolean indicator for whether p-values should
##' correspond to a two-sided test or one-sided. Defaults to
##' \code{TRUE}.
##' @param ci.level Confidence level. Defaults to 0.95.
##' @return S4 \code{inference} object.
##' @examples
##' infer(lm(rnorm(100) ~ runif(100)))
##' @author Vinh Nguyen
setGeneric("infer", function(fitobj, ...) standardGeneric("infer"))

##' @rdname infer,-methods
setMethod("infer", signature(fitobj="lm"),...})

##' @rdname infer,-methods
setMethod("infer", signature(fitobj="glm"),...)

I just want to let everyone out there know that you still need to
declare @rdname for each of the setMethod, as leaving this out will
generate an "empty" (not much info) infer,-method.Rd file being
overwritten many times; I believe roxygen's default settings generate
an Rd file when it sees no roxygen documentation prior to the
setMethod definition. This file will also have \alias{infer} in it,
which will take precedence when you type ?infer (so you'll see an
"empty" file).

Vinh