Documenting reference class with roxygen2 R CMD check codoc mismatches warning

Question

I am trying to use roxygen2 to make documentation for a reference class object, but I keep getting this warning when I run R CMD check:

  S4 class codoc mismatches from documentation object 'myRefClass-class':
  Slots for class 'myRefClass'
  Code: .xData
  Inherited: .xData
  Docs: field1 field2

This is the ref class and roxygen2 block associated with above warning:

#' @title myRefClass class
#' @description Description of myRefClass
#' @import methods
#' @exportClass myRefClass
#' @slot field1 A character slot
#' @slot field2 A numeric slot
myRefClass<-setRefClass(Class="myRefClass", 
                        fields=list(field1="character", 
                        field2="numeric"))

Here is the R documentation that was generated:

myRefClass-class {testPackaging} R Documentation myRefClass class

Description

Description of myRefClass

Slots

field1 A character slot

field2 A numeric slot

As to the documentation I could find, codoc is testing for consistency between my code and the documentation. From what I can tell, all the slot names are the same; perhaps I'm missing something. Not sure if the documentation should have automatically marked this as a reference class, or if I should have indicated that in some way? I've found R documentation indicating that the slot, ".xData, is used to enable inheritance from abnormal types", but I am not sure why it applies to what I'm doing here or if I should be doing something with it.

I have tried a number of permutations of the roxygen tags and keeping close to the structure found here seems to be giving me the best result/least warnings from R CMD check: Roxygen2 - how to @export reference class generator? I've been looking around the net for examples of how roxygen2 should be used with reference classes; maybe I'm looking in the wrong places -- I haven't had much luck.

I am using roxygen2 v 3.1.0 / RStudio Version 0.98.501 / R version 3.0.3 / OSX 10.9.2 (note: tried upgrading to roxygen2 v 4.0 and it completely choked on the reference class to the point that no documentation was being generated at all)

If some one knows of a CRAN package using roxygen2 and reference classes, so that I might see how it's done properly, or if some one knows what it is that I'm doing wrong, the help would be much appreciated. I am new at package building in R.

Answer 1

I normally use an @section Fields so in this case:

#' @title myRefClass class
#' @description Description of myRefClass
#' @import methods
#' @exportClass myRefClass
#' @section Fields:
#' \describe{
#' \item{\code{field1}:}{Object of class \code{"character"}, field1 description here}
#' \item{\code{field2}:}{Object of class \code{"numeric"}, field2 description here}
#' }

myRefClass<-setRefClass(Class="myRefClass", 
                        fields=list(field1="character", 
                        field2="numeric"))

UPDATE: using roxygen2 4.0.1

#' A Reference Class to represent test1.
#' @name test1
#' @import methods
#' @exportClass myRefClass
#' @field field1 A character vector
#' @field field2 A numeric vector

myRefClass<-setRefClass(Class="myRefClass", 
                        fields=list(field1="character", 
                                    field2="numeric"))

produces

A Reference Class to represent test1.
Description

A Reference Class to represent test1.
Fields

field1

    A character vector
field2

    A numeric vector