Extending/adding to an R6 class from another package: qns
hongooi @ending from micro@oft@com
Fri Oct 19 01:16:11 CEST 2018
I'm writing a family of packages for talking to Azure (Microsoft's cloud service) from R. The basic architecture is
AzureRMR: the "base" package, provides a number of R6 classes
AzureVM: a "child" package that extends classes from AzureRMR with extra functionality related to virtual machines
AzureStor: another child package that extends classes from AzureRMR, this time for storage accounts
For example, AzureRMR defines a class called "az_resource_group" that represents an Azure resource group. Within this class, I have convenience functions to manage individual Azure resources: az_resource_group$get_resource(), az_resource_group$create_resource(), etc. One benefit of this approach is that method chaining works: I can do something like
In my child packages, I then define further classes and methods for dealing with specific services. For consistency, I also add convenience functions to the base AzureRMR::az_resource_group class to work with these new classes. For example, AzureVM defines a new class az_vm_template, and also adds a $get_vm() method to AzureRMR::az_resource_group.
Running devtools::check() however brings up a note and warning for the child packages. For example, with AzureVM:
* checking R code for possible problems ... NOTE
message("Creating resource group '", resource_group, "'")
Package startup functions should use 'packageStartupMessage' to generate messages.
See section 'Good practice' in '?.onAttach'.
. . .
* checking for code/documentation mismatches ... WARNING
Functions or methods with usage in documentation object 'get_vm' but not in code:
get_vm get_vm_cluster list_vms
The reason for the note is because modifying R6 classes from another package has to be done at runtime, ie, in the .onLoad function. The message() call referred to is inside one of the new methods that I define for an AzureRMR class, hence it never actually appears at package startup. I assume it's okay to ignore this note?
The reason for the warning is because writing documentation for R6 methods is rather awkward, even/especially with Roxygen. This goes doubly so when the method in question is for a class from a different package. What I've done is to write a Roxygen block for the method as if it was a standalone function; for example, the documentation for az_resource_group$get_vm() is like this:
#' Get existing virtual machine(s)
#' Method for the [AzureRMR::az_subscription] and [AzureRMR::az_resource_group] classes.
#' @rdname get_vm
#' @name get_vm
#' get_vm(name, resource_group = name)
#' @param name The name of the VM or cluster.
#' @param resource_group For the `az_subscription` method, the resource group in which `get_vm()` will look for the VM. Defaults to the VM name.
This way, typing ?get_vm will bring up the relevant page, which seems to me to be the best compromise in terms of the end-user experience. Is this an acceptable way of doing the documentation for CRAN?
More information about the R-package-devel