How do I indicate collate order in Roxygen2?

9
votes

Using roxygen2 documentation with devtools document function automatically generates a Collate: field in the package DESCRIPTION, regardless of whether or not it is necessary to load the package library files in a particular order.

I'm working on a package with a bunch of S4 methods and want to be sure the class definitions are loaded before any methods or other classes using them, which I understand I can do with the Collate list, but I'm not sure how to indicate this in the roxygen2 documentation format.

The roxygen2 manual makes some reference to an @include tag but that looks like it might actually just include code in the documentation, for instance, for adding external examples through an @examples flag. Can this be used for specifying collate order for methods?

2
rdocumentation-generationroxygen2
If the collate field is already in the DESCRIPTION roxygen2 doesn't generate it. So I'd say you have to make the order you want and it should be respected. (I think; hence the comment vs an answer). – Tyler Rinker
it would be nice to know if my @import interpretation is correct. It also certainly would be nice to have a function figure out the collate order from a list of file dependencies rather than having to work it out manually. – cboettig
import is used to import a package. This is similar to listing a package in the Depends section except that it is much cleaner because it doesn't pollute the user's namespace. – Dason
And let me save you future heart ache by saying @importfrom is even better because it avoids naming conflicts. – Tyler Rinker
whoops, I meant to say @include is the tage I don't understand, sorry for the typo. Text changed above. What's up with the @include tag and how does it relate to Collate ordering? – cboettig

2 Answers

15
votes

The include tag is used to state that one file needs another to work. (The name include might not have been the best choice, but such is life). If you want to make sure that file B is loaded before file A, then make sure to @include B in A. Roxygen will take care of ordering the collate field to satisfy your restrictions.

5
votes

I just figured out that if you add the @include statement at the top of your R file, it will interfere with the next roxygen2 documentation block unless you follow it with a NULL eg

#' @include something.R
NULL

#' Documenting a function
#'
#" It does something...
#'
#' @param ...
#'