I am trying to design a S4 class with my own initialization method and separately document them with Roxygen2. Assuming my class is defined as:
#' This is the classA
#' @name classA-class
#' @rdname classA-class
######## @aliases NULL
#' @exportClass classA
classA <- setClass(Class = "classA", slots = list(member = "ANY"))
With the initialization method:
#' This is the constructor
#' @name classA
#' @rdname classA
#' @export classA
setMethod("initialize", "classA", function(.Object, x) {
.Object@member = x
return(.Object)
})
After compiling the package with Roxygen2. I got 2 .Rd files with 3 help page:
Both class?classA
and ?classA
will show classA-class
help page. This is definitely what I want as I hope class?classA
will lead to classA-class: This is the classA
while ?classA
will lead to classA: This is the constructor
.
So, my question is how to separate the class documentation and constructor documentation with Roxygen2? Thank you so much for all your help.
(I understand that Roxygen2 will put aliases with the class name for S4 class by default. But when I set @aliases NULL
, the classA-class: This is the classA
help page disappeared!! left only the classA: This is the constructor
)
The reasons that both help files show up under the class documentation is that the setClass
always uses the class name as an alias for the class in the documentation. In addition, your method for the generic initialize
defined for classA
specifies @rdname classA
which points it to the classA-method
.
Here are two solutions:
First, you can simplify the Roxygen2 header codes and get the behaviour you want, but you will need to use @name
to call the initialize method something other than classA
.
#' \code{classA} class definition
#'
#' @slot member description of this slot here
classA <- setClass(Class = "classA", slots = list(member = "ANY"))
#' constructor for \link{classA-class}
#'
#' This is the constructor.
#' @name initializeClassA
#' @export
setMethod("initialize", "classA", function(.Object, x) {
.Object@member = x
return(.Object)
})
That gives you the classA-class page for ?classA
and ?"classA-class"
but for the constructor, you get whatever name you used after @rdname
, e.g. ?initializeClassA
, if that's what you want.
Second, I would recommend that you not use initialize
at all, instead create new instances of classA
using new("classA", memberValue)
. You can define a prototype in the class definition to assign default values of member
if you want, and/or validator functions. Do you really need a separate help page for the constructor?