Search code examples
roxygen2roxygen

roxygen2 docstrings for Reference Classes overriding base class

I have an abstract base class that looks like this:

#' An Abstract Base Class 
Filter <- setRefClass(
  Class = "Filter",
  methods = list(
    train = function(x) {
      "Override this method to train any associated parameters for the filter on the supplied data"
  print("no learning to be done")
})
)

and the following class that extends this class:

#' Filter class that leverages the prcomp R method. 
PcaFilter <- setRefClass(
  "PcaFilter",
  contains="Filter",
  fields=list(
    d="numeric",
    model="ANY"
    ),
  methods=list(
    train=function(x) {
      "train PCA model, store result to model attribute of obj"
      model <<- prcomp(x)
    })
)

After I run

roxygen2::roxygenize()

Then I get two man files but in the man file for the second class the docstring for the overridden class does not come through- I get the docstring for the base class. Am I doing something wrong or is this a bug with roxygen2 ?

Also is there any better way of doing this? I would like to be able to use multi-line docstrings.

Solution

  • Having searched through the Issues on the roxygen github repo. Found that there's already an active Issue pertaining to this:

    https://github.com/klutometis/roxygen/issues/433

    In summary: the support and documentation for Reference Classes in roxygen is not great as of v5.0. The suggested method is still to use docstrings and it's impossible to override the docstrings of parents.