I'm writing an R package and currently running R CMD check via devtools::check()
I have the following roxygen2 in two of my functions that reference an S4 class (both functions return objects of this class):
#' #return An object of class \code{\link{mod_imputeMulti}}
#' #aliases mod_imputeMulti
#' #seealso \code{\link{multinomial_em}}, \code{\link{multinomial_impute}}
Yet I get the following WARNING:
Rd files with duplicated alias 'mod_imputeMulti':
'multinomial_data_aug.Rd' 'multinomial_em.Rd'
If I don't use second line -- the #aliases tag, I get this WARNING, despite the fact that I do have a link:
checking Rd cross-references ... WARNING
Missing link or links in documentation object 'multinomial_data_aug.Rd':
'mod_imputeMulti'
Missing link or links in documentation object 'multinomial_em.Rd':
'mod_imputeMulti'
See section 'Cross-references' in the 'Writing R Extensions' manual.
Note: adding \code{\link{mod_imputeMulti}} to #seealso doesn't change this (second) WARNING
What is the correct syntax?
I've looked at a lot of references but can't find the solution anywhere:
Hadley's book
The R extensions manual-cross references
The roxygen2 manual
this SO answer
I hope this is an easy one for someone--thanks in advance for the help!
Edit:
The S4 class documenation is provided below:
#' Class "mod_imputeMulti"
#'
#' #name mod_imputeMulti-class
#' #description A multivariate multinomial model imputed by EM or Data Augmentation is
#' represented as a \code{\linkS4class{mod_imputeMulti}} object. A complete
#' dataset and model is represented as an \code{\linkS4class{imputeMulti}} object.
#' Slots for \code{mod_imputeMulti} objects include: (1) the modeling method;
#' (2) the call to the estimation function; (3) the number of iterations in estimation;
#' (4) the final log-likelihood; (5) the conjugate prior if any; (6) the MLE estimate of
#' the sufficient statistics and parameters.
#' #docType class
#' #section Objects from the class: Objects are created by calls to
#' \code{\link{multinomial_impute}}, \code{\link{multinomial_em}}, or
#' \code{\link{multinomial_data_aug}}.
#' #seealso \code{\link{multinomial_impute}}, \code{\link{multinomial_em}},
#' \code{\link{multinomial_data_aug}}
#' #export
setClass("mod_imputeMulti",
representation= list(
method= "character",
mle_call= "call",
mle_iter= "numeric",
mle_log_lik= "numeric",
mle_cp= "character",
mle_x_y= "data.frame"),
validity= function(object) {
if (!object#method %in% c("EM", "DA", "NULL")) {
return("Currently only EM and DA methods are defined.")
} else if (object#mle_iter < 0) {
return("A negative iteration was given.")
}
return(TRUE)
}
)
Yes, this was a relatively simple fix.
As you can see in the S4 class documenation at the bottom of the OP, note that the name is mod_imputeMulti-class, not mod_imputeMulti.
I needed to add "-class". The #aliases tag is unneeded.
#' #return An object of class \code{\link{mod_imputeMulti-class}}
Also, thanks to #thomas for pointing out the use of #slot for proper translation of the roxygen2 tagging to man/*.Md files.
Related
I'm writing an R package where I implement my own 'predict' generic and an S4 method for the signature 'apk', which is an S4 class inside my package as well. I'm using Rstudio as editor and generating the documentation with Roxygen2.
All the problem goes about the autocompletion candidates that Rstudio shows when I type predict once the package is installed and loaded. Just after opening a new R session, if I type predict, I get the following candidates: predict {aPack}, predict {stats}, predict.glm {stats} and predict.lm {stats}. Note that both, the S4 from my package aPack and the one from stats are displayed as candidates. This happens because right before setting the generic, I imported predict from stats as suggested in this SO answer.
The problem: when I load another package with an S4 predict method, I'm no longer able to make my S4 show as autocomplete candidate. For instance, if I load the DiceKriging package and mine in the same session I only get the following candidates: predict {DiceKriging}, predict {stats}, predict.glm {stats}, predict.lm {stats} and predict.km {DiceKriging}. Once I load DiceKriging it is not possible to get my S4 displayed in autocomplete even if I load my package again. The predict method still works without predict {aPack} being listed by the autocompletion system, however, I would like to make it visible so that the user gets directly aware of the availability of my method.
Question: how sould I modify my roxygen documentation so that predict {aPack} gets prompted by the autocompletion system even if I load another package with a predict S4 method?
Minimal reproducible example
#' #title Class: apk model
#' #description To create an apk object, use \link[aPack]{apk}.
#' #slot call Object of class \code{"language"}. User call reminder.
#' #rdname apk-class
#' #import methods
#' #export
setClass("apk", representation(call = "language"), validity = function(object) {T})
#' #title Create an Object of class \code{"apk"}
#' #description Creator function for objects of class \code{"apk"}.
#' #param foo Not used yet.
#' #param ... Not used yet.
#' #export
apk <- function(foo, ...) {
new("apk")
}
#' #name predict
#' #rdname predict-methods
#' #importFrom stats predict
#' #param object An object to predict from.
#' #param ... Further arguments for methods.
#' #export predict
setGeneric(name = "predict", def = function(object, ...) standardGeneric("predict"))
predict.apk <- function(object, bar, ...) {
print("I'm an apk prediction!")
}
#' #title Prediction Method for the apk Class
#' #name predict
#' #rdname predict-methods
#' #aliases predict,apk-method
#' #examples
#' myApk <- apk()
#' predict(myApk)
setMethod("predict", "apk", predict.apk)
GitHub: I also uploaded the project to GitHub so that you can directly make your suggested changes there if you want. The repository is here.
I wrote a show() method for the S4 class myclass which I had defined in my package. I generated documentation for class and method with roxygen2. Everything works nicely, except that I get the following warning in R CMD check results:
checking for missing documentation entries ... WARNING
Undocumented S4 methods:
generic 'length' and siglist 'myclass'
How do I go about documenting show generic which I did not write myself?
In the end, using explicit #aliases and #docType tags solved the issue for me. My documentation block now looks like this:
#' Show method for objects of class \code{myclass}.
#'
#' #docType methods
#' #name show-myclass
#' #rdname show-myclass
#' #aliases show-myclass show,myclass-method
#'
#' #param x A \code{myclass} object.
#'
#' #export
I am writing a package that defines a new class, surveyor, and a print method for this, i.e. print.surveyor. My code works fine and I use roxygen for inline documentation. But R CMD check issues a warning:
Functions/methods with usage in
documentation object 'print.surveyor'
but not in code: print
I have used the following two pages, written by Hadley, as inspiration:
Namespaces and Documenting functions, both of which states that the correct syntax is #method function-name class
So my question is: What is the correct way of documenting the print method for my new class using Roxygen? And more specifically, how do I get rid of the warning?
Here is my code: (The commented documentation indicated attempts at fixing this, none of which worked.)
#' Prints surveyor object.
#'
#' Prints surveyor object
#'
## #' #usage print(x, ...)
## #' #aliases print print.surveyor
#' #param x surveyor object
#' #param ... ignored
#' #S3method print surveyor
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
And the roxygenized output, i.e. print.surveyor.Rd:
\name{print.surveyor}
\title{Prints surveyor object.}
\usage{print(x, ...)
#'}
\description{Prints surveyor object.}
\details{Prints surveyor object
#'}
\alias{print}
\alias{print.surveyor}
\arguments{\item{x}{surveyor object}
\item{...}{ignored}}
Update
As of roxygen2 > 3.0.0 the package has gotten a lot smarter at figuring all this out for you. You now just need the #export tag and roxygen will work out what kind of thing you are documenting and do the appropriate thing when writing the NAMESPACE etc during conversion.
There are exceptions where you may need to help out roxygen. An example that Hadley Wickham uses in his R Packages book is all.equal.data.frame. There is ambiguity in that function name as to what is the class and what is the generic function (all, all.equal, or all.equal.data)?
In such cases, you can help roxygen out by explicitly informing it of the generic and class/method, e.g.
#method all.equal data.frame
The original answer below explains more about the older behaviour if you need to explicitly use #method.
Original
The function should be documented with the #method tag:
#' #method print surveyor
On initial reading, #hadley's document was a little confusing for me as I am not familiar with roxygen, but after several readings of the section, I think I understand the reason why you need #method.
You are writing full documentation for the print method. #S3method is related to the NAMESPACE and arranges for the method to be exported. #S3method is not meant for documenting a method.
Your Rd file should have the following in the usage section:
\method{print}{surveyor}(x, ...)
if this works correctly, as that is the correct way to document S3 methods in Rd files.
As of roxygen2 > 3.0.0., you only need #export because roxygen can figure out that print.surveyor is an S3 method. This means that you now only need
#' Prints surveyor object.
#'
#' #param x surveyor object
#' #param ... ignored
#' #export
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
However, in this case since the documentation isn't very useful, it'd probably better to just do:
#' #export
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
#export only works if the generic is loaded. If the generic is in another package you need to import the generic. With current roxygen this is solved with a block like
#' #importFrom tibble data_frame
#' #export
tibble::data_frame
taken from dplyr/R/reexport-tibble.r . In this example, the data_frame method is imported from the tibble package, and tibble::data_frame is exported. Such re-exported objects are then documented in a reexports.Rd file that - needless to say - satisfies R CMD check.
I am writing a package that defines a new class, surveyor, and a print method for this, i.e. print.surveyor. My code works fine and I use roxygen for inline documentation. But R CMD check issues a warning:
Functions/methods with usage in
documentation object 'print.surveyor'
but not in code: print
I have used the following two pages, written by Hadley, as inspiration:
Namespaces and Documenting functions, both of which states that the correct syntax is #method function-name class
So my question is: What is the correct way of documenting the print method for my new class using Roxygen? And more specifically, how do I get rid of the warning?
Here is my code: (The commented documentation indicated attempts at fixing this, none of which worked.)
#' Prints surveyor object.
#'
#' Prints surveyor object
#'
## #' #usage print(x, ...)
## #' #aliases print print.surveyor
#' #param x surveyor object
#' #param ... ignored
#' #S3method print surveyor
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
And the roxygenized output, i.e. print.surveyor.Rd:
\name{print.surveyor}
\title{Prints surveyor object.}
\usage{print(x, ...)
#'}
\description{Prints surveyor object.}
\details{Prints surveyor object
#'}
\alias{print}
\alias{print.surveyor}
\arguments{\item{x}{surveyor object}
\item{...}{ignored}}
Update
As of roxygen2 > 3.0.0 the package has gotten a lot smarter at figuring all this out for you. You now just need the #export tag and roxygen will work out what kind of thing you are documenting and do the appropriate thing when writing the NAMESPACE etc during conversion.
There are exceptions where you may need to help out roxygen. An example that Hadley Wickham uses in his R Packages book is all.equal.data.frame. There is ambiguity in that function name as to what is the class and what is the generic function (all, all.equal, or all.equal.data)?
In such cases, you can help roxygen out by explicitly informing it of the generic and class/method, e.g.
#method all.equal data.frame
The original answer below explains more about the older behaviour if you need to explicitly use #method.
Original
The function should be documented with the #method tag:
#' #method print surveyor
On initial reading, #hadley's document was a little confusing for me as I am not familiar with roxygen, but after several readings of the section, I think I understand the reason why you need #method.
You are writing full documentation for the print method. #S3method is related to the NAMESPACE and arranges for the method to be exported. #S3method is not meant for documenting a method.
Your Rd file should have the following in the usage section:
\method{print}{surveyor}(x, ...)
if this works correctly, as that is the correct way to document S3 methods in Rd files.
As of roxygen2 > 3.0.0., you only need #export because roxygen can figure out that print.surveyor is an S3 method. This means that you now only need
#' Prints surveyor object.
#'
#' #param x surveyor object
#' #param ... ignored
#' #export
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
However, in this case since the documentation isn't very useful, it'd probably better to just do:
#' #export
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
#export only works if the generic is loaded. If the generic is in another package you need to import the generic. With current roxygen this is solved with a block like
#' #importFrom tibble data_frame
#' #export
tibble::data_frame
taken from dplyr/R/reexport-tibble.r . In this example, the data_frame method is imported from the tibble package, and tibble::data_frame is exported. Such re-exported objects are then documented in a reexports.Rd file that - needless to say - satisfies R CMD check.
I am writing a package that defines a new class, surveyor, and a print method for this, i.e. print.surveyor. My code works fine and I use roxygen for inline documentation. But R CMD check issues a warning:
Functions/methods with usage in
documentation object 'print.surveyor'
but not in code: print
I have used the following two pages, written by Hadley, as inspiration:
Namespaces and Documenting functions, both of which states that the correct syntax is #method function-name class
So my question is: What is the correct way of documenting the print method for my new class using Roxygen? And more specifically, how do I get rid of the warning?
Here is my code: (The commented documentation indicated attempts at fixing this, none of which worked.)
#' Prints surveyor object.
#'
#' Prints surveyor object
#'
## #' #usage print(x, ...)
## #' #aliases print print.surveyor
#' #param x surveyor object
#' #param ... ignored
#' #S3method print surveyor
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
And the roxygenized output, i.e. print.surveyor.Rd:
\name{print.surveyor}
\title{Prints surveyor object.}
\usage{print(x, ...)
#'}
\description{Prints surveyor object.}
\details{Prints surveyor object
#'}
\alias{print}
\alias{print.surveyor}
\arguments{\item{x}{surveyor object}
\item{...}{ignored}}
Update
As of roxygen2 > 3.0.0 the package has gotten a lot smarter at figuring all this out for you. You now just need the #export tag and roxygen will work out what kind of thing you are documenting and do the appropriate thing when writing the NAMESPACE etc during conversion.
There are exceptions where you may need to help out roxygen. An example that Hadley Wickham uses in his R Packages book is all.equal.data.frame. There is ambiguity in that function name as to what is the class and what is the generic function (all, all.equal, or all.equal.data)?
In such cases, you can help roxygen out by explicitly informing it of the generic and class/method, e.g.
#method all.equal data.frame
The original answer below explains more about the older behaviour if you need to explicitly use #method.
Original
The function should be documented with the #method tag:
#' #method print surveyor
On initial reading, #hadley's document was a little confusing for me as I am not familiar with roxygen, but after several readings of the section, I think I understand the reason why you need #method.
You are writing full documentation for the print method. #S3method is related to the NAMESPACE and arranges for the method to be exported. #S3method is not meant for documenting a method.
Your Rd file should have the following in the usage section:
\method{print}{surveyor}(x, ...)
if this works correctly, as that is the correct way to document S3 methods in Rd files.
As of roxygen2 > 3.0.0., you only need #export because roxygen can figure out that print.surveyor is an S3 method. This means that you now only need
#' Prints surveyor object.
#'
#' #param x surveyor object
#' #param ... ignored
#' #export
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
However, in this case since the documentation isn't very useful, it'd probably better to just do:
#' #export
print.surveyor <- function(x, ...){
cat("Surveyor\n\n")
print.listof(x)
}
#export only works if the generic is loaded. If the generic is in another package you need to import the generic. With current roxygen this is solved with a block like
#' #importFrom tibble data_frame
#' #export
tibble::data_frame
taken from dplyr/R/reexport-tibble.r . In this example, the data_frame method is imported from the tibble package, and tibble::data_frame is exported. Such re-exported objects are then documented in a reexports.Rd file that - needless to say - satisfies R CMD check.