How can I document datasets without adding them to the Collate field?

Question

I'm using roxygen2 to document datasets for a package I'm developing. I know you can use roxygen to document a dataset, but Shane's answer ultimately suggests a hack, which while I'd rather avoid. So, my question is:

Where should I put roxygen documentation for data?

I currently have a data documentation file (anorexia.sub.roxygen) for an anorexia dataset in my /R folder

because as far as I can tell, that's the only place roxygen2 will look for it:

#' Family Treatment Weight change data for young female anorexia patients.
#' 

#' 
#' The MASS package includes the dataset \code{anorexia}, containing pre and
#' post treatment weights for young female anorexia patients.  This is a subset
#' of those data, containing only those patients who received Family Treatment.
#' 
#' 
#' @name anorexia.sub
#' @docType data
#' @format A dataframe with 17 observations on the following 2 variables, no
#'   NAs.
#'
#' \describe{
#' 
#' \item{list("Prewt")}{Pretreatment weight of subject, in pounds.}
#' 
#' \item{list("Postwt")}{Postreatment weight of subject, in pounds.}
#' 
#' }
#' @references Venables, W. N. and Ripley, B. D. (2002) Modern Applied
#'   Statistics with S. Fourth edition. Springer.
#' @source Hand, D. J., Daly, F., McConway, K., Lunn, D. and Ostrowski, E. eds
#'   (1993) A Handbook of Small Data Sets. Chapman & Hall, Data set 285 (p.
#'   229)
#' @keywords datasets
NULL

roxygen2 generates the documentation just fine. But, then it ADDS anorexia.sub.roxygen.R to my Collate field in DESCRIPTION:

Collate:
    'granova.R'
    'theme-defaults.R'
    'granovagg.1w.R'
    'granovagg.contr.R'
    'granovagg.ds.R'
    'help.R'
    'anorexia.sub.roxygen.R'

I guess my question is: how can I have roxygen2

1. automatically generate data documentation from roxygen blocks,
2. NOT add the data documentation file to the Collate call, AND
3. avoid a solution that requires a hack

Hampstead

Answer 1

Since it is good practise to document your package at the package level as well as function level, I always have a file inside the R folder called packagename-package.R (e.g. granovaGG-package.R in your case) where I keep the package documentation as well as data documentation.

So your granovaGG-package.R file might look something like:

#' One sentence summary of your package.
#' 
#' More detail
#' ...
#' @name granovaGG-package
#' @aliases granovaGG
#' @docType package
#' @title One sentence summary of your package.
#' @author \email{your.name@@email.com}
#' @keywords package
#' @seealso \code{\link{...}}
NULL
#' Your dataset documentation goes here.
#' 
#' Exactly as in your example.
#' @docType data
#' etc.
#' ...
NULL

Chimere

I didn't realize you could have multiple roxygen blocks in the same file! That should work perfectly. Thanks, Andrie! – Hampstead

I'm glad it helped. I should have said in the original answer that you can, of course, add your data documentation to any other file! – Chimere

Can I assume that's not a literal NULL, but rather just a blank line? (I'm not an roxygen writer, yet) – Buff

Well, the answer is it depends. Roxygen requires at least one line of valid R code (not Roxygen code) in the file. NULL satisfies that, but if you have other R code in the file you don't need the NULL. – Chimere

Just an anecdote for those who follow: when I was documenting two data sets in my packagename-package.R file, I had to include a NULL between each block in order to get the .Rd files to generate correctly. – Cysticercoid