Documenting R6 objects

[kenahoo]

I asked this question on Stack Overflow about how to document R6 objects, but no answers yet after a week: https://stackoverflow.com/questions/53750453/roxygen-r6-methods . Wondering if someone here might have a suggestion.

(I know R6 documentation is an oft-desired topic, as shown in the uncompleted issues #388, #306, etc. - basically I'm trying to "punt" and not need Roxygen to know anything about R6; I'm just trying to use some existing Roxygen features like @inheritParams etc. and have R CMD check not yell at me.)

Question repeated here:

---

I'm trying to generate some reasonable documentation for R6 classes. Here's an example:

##' GroveR class object
##' @importFrom R6 R6Class
##' @export
GroveR <- R6Class(
  portable = FALSE,
  private = list(
    fileRoot = ".",
    artDefs = list(),
    memCache = list()
  )
)

.public  <- function(...) GroveR$set("public",  ...)

#' Do a thing
#'
#' @name myMethod
#' @usage
#' myMethod(name, deps, create, retrieve, checkTime,
#'          store, clobber=FALSE)
#'
#' @param name name of the artifact
#' @param deps names of other artifacts this artifact depends on
#' @param create function to create this artifact object from its dependency objects
#' @param retrieve function to retrieve this artifact from cache
#' @param checkTime function to fetch the time of last update for this artifact
#' @param store function to store this artifact to cache
#' @param clobber whether to allow redefinition of this artifact if it is already defined
.public("myMethod", function(name, deps, create, retrieve, checkTime, store, clobber=FALSE) {
  # ...body...
}

#' Do a similar thing
#'
#' @name myOtherMethod
#' myOtherMethod(name, deps, create, path, readFun=readRDS,
#'               writeFun=saveRDS, ...)
#'
#' @inheritParams myMethod  // TODO Doesn't work yet
#' @param path path to cached file
#' @param readFun function to read file from disk
#' @param writeFun function to write file to disk
#' @param ... further arguments passed to \link{myMethod}
.public("myOtherMethod", function(name, deps, create, path, readFun=readRDS, writeFun=saveRDS, ...) {
  # ...body...
}

.public() is a helper function I've written for defining R6 methods.

There are several things not working here:

• The @inheritParams directive is not working, the name and deps and create argument for myOtherMethod() are not being inherited. This generates R CMD check warnings like Undocumented arguments in documentation object 'myOtherMethod' ‘name’ ‘deps’ ‘create’
• I'm adding the @usage directive manually, because Roxygen can't figure out (quite reasonably) how to parse my method definitions. Is there a better way to do this?
• In R CMD check, I get warnings about Functions or methods with usage in documentation object 'myMethod' but not in code: myMethod

Is there a more fruitful direction for me to go? Should I try documenting a NULL object instead of my .public calls? What would that look like?

[gaborcsardi]

Duplicate of #388.

See existing packages for what you can do right now. E.g. processx or webdriver, etc.

[kenahoo]

Hi @gaborcsardi , I mentioned #388 in my question too, but it doesn't explain the behavior I'm seeing (or whatever my misunderstanding of the @inheritParams directive might be). Doesn't seem like the same question to me.

[kenahoo]

I'm going to close this ticket and open a new ticket that simplifies the issue and takes R6 out of the picture - to me this is just a vanilla roxygen problem or misunderstanding, R6 is just what I happen to be documenting, but roxygen doesn't really know that.