How to specify in which order to load S4 methods when using roxygen2

Question

I ran into following problem already multiple times.

Say you have two classes, classA and classB described in the following files classA.R :

#' the class classA
#'
#' This is a class A blabla
#' \section{Slots}{\describe{\item{\code{A}}{a Character}}}
#' @ name classA
#' @rdname classA
#' @exportClass classA
setClass("classA",representation(A="character"))

And classB.R

#' the class classB
#'
#' This is a class B blabla
#' \section{Slots}{\describe{\item{\code{B}}{an object of class A}}}
#' @ name classB
#' @rdname classB
#' @exportClass classB
setClass("classB",representation(B="classA"))

I believed these files were read in alphabetical order by roxygen2, but that is not the case. If I try to build the package, I might get the following error:

roxygenize("./myExample")
Error in getClass(Class, where = topenv(parent.frame())) :
   "ClassA" is not a defined class

How can I make sure that roxygenize() knows in which order to read the files, i.e. which class definition should be read before the other?

---

Note : I know I answered my own question. That is because I ran into this problem rather often, and realized the proper way to do this after looking at the code of roxygen2. So for reference, here's my findings.

Answer 1

There are two ways to achieve this:

As described in ?collate_roclet, you can use the @include tag to specify which class should be read before which. In this case, you can add to the file classB.r the following line right before the actual R code:

#' @include classA.r

These tags are read specifically to update the Collate field in the DESCRIPTION file, and are the recommended way of dealing with the problem.

In some cases the dependencies might be so complex you want to keep an overview yourself and not rely completely on adding @include tags in your codebase. In that case you can just specify the Collate field at the end of the DESCRIPTION file, like this:

Package: myExample
Type: Package
...
Collate:
    'classA.R'
    'classB.R'

The function roxygenize() first checks the DESCRIPTION file, and loads whatever files are specified there first in the order they're specified. Only then the rest of the package is loaded.