Is there anyway to document S4 class and its constructor separately using Roxygen2

Question

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:

• classA-class: This is the classA
• classA: This is the classA
• classA: This is the constructor

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)

Answer 1

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?