--- Begin Message ---
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
Etc.
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
az_subscription("xxx")$get_resource_group("yyy")$get_resource("zzz").
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
File 'AzureVM/R/add_methods.R':
.onLoad calls:
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
#' @usage
#' get_vm(name)
#' 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.
#'
#' @details
#' ...
NULL
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?
Hong
--- End Message ---
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
