I have updated to roxygen2 v4.0.0 and am now attempting to convert #S3method and #method commands to #export commands following the directions here. This seems to have worked well for all of my methods except for those related to print.
Here is a toy example that illustrates my problem (I understand the silliness of the example). Here is the .R file ...
#' Test.
#'
#' Test.
#'#aliases zzzTest print.zzzTest summary.zzzTest
#'#param v A numeric vector.
#'#param x A \code{zzzTest} object.
#'#param object A \code{zzzTest} object.
#'#param \dots Additional arguments for the S3 methods.
#'#return A \code{zzzTest} object.
#'#keywords manip
#'#examples
#'z <- zzzTest(runif(10,1,2))
#'print(z)
#'summary(z)
#'#rdname zzzTest
#'#export zzzTest
zzzTest <- function(v) {
tmp <- log(v)
class(tmp) <- "zzzTest"
}
#'#rdname zzzTest
#'#export
print.zzzTest <- function(x,...) { print(x, ...) }
#'#rdname zzzTest
#'#export
summary.zzzTest <- function(object,...) { summary(object) }
And this is the .Rd file that results from roxygenising ...
% Generated by roxygen2 (4.0.0): do not edit by hand
\name{zzzTest}
\alias{print.zzzTest}
\alias{summary.zzzTest}
\alias{zzzTest}
\title{Test.}
\usage{
zzzTest(v)
print.zzzTest(x, ...)
\method{summary}{zzzTest}(object, ...)
}
\arguments{
\item{v}{A numeric vector.}
\item{x}{A \code{zzzTest} object.}
\item{object}{A \code{zzzTest} object.}
\item{\dots}{Additional arguments for the S3 methods.}
}
\value{
A \code{zzzTest} object.
}
\description{
Test.
}
\examples{
z <- zzzTest(runif(10,1,2))
print(z)
summary(z)
}
\keyword{manip}
My use of #export seems to work fine for the summary method (note the \method()), but not for the print method (note no \method() and only print.zzzTest). I was also successful using #export for several other methods in other .R files. My problems only seem to occur with the print method.
Can someone point out where I am going wrong? Thank you in advance for any help with this problem.
For what it is worth, I am using R 3.1.0, RStudio 0.98.501, and roxygen2 4.0.0.
UPDATE 1: There is an export(print.zzzTemp) but not an S3method(print,zzzTemp) in the namespace ... i.e., the same problem as ZNK (in the comments).
UPDATE 2: I copied the exact .R file into another package, roxygenized that package, and the .Rd file (and corresponding namespace) were created properly. This implies that I have some "switch" related to roxygen2 different between the two packages, but I can't seem to isolate the difference or find such a "switch" (I believe that I have only controlled roxygen through the project options in RStudio).
I have found a solution for my problem (In comments above) and it may work for yours. In The NEWS.md file for v3.0.0, it is mentioned that #method tag is not needed as roxygen2 will figure it out, but it's sill available in the rare case that roxygen2 cannot do so. My solution:
#' #method print myClass
#' #export
print.myClass <- function(x) print("myClass")
This gives me back the S3method(print, myClass) in my NAMESPACE file.
The 16th line of your code
#'#export zzzTest
needs to be
#'#export
as mentioned by Hadley in this link.
You might also need to remove the 2nd and 3rd instance of #export. And don't forget to do devtools::document() before building/checking.
The coding I outlined above worked for me until I added a #useDynLib pkg-name tag. Then I had to resort to the #method tag to get the desired NAMESPACE after devtools::document().
Related
In my R package, a few functions are omitted from the package manual .pdf file - and they are all S3 methods where several functions are documented together. All other "normal" functions appear correctly, so I suspect I'm not documenting the S3 methods correctly.
I want an entry for myfun to appear in the manual. Right now, the function is missing from the .pdf manual entirely, though it can still be called correctly and its help page referenced with ?myfun. Are my Roxygen2 keywords wrong?
#' #export
myfun <- function(...) UseMethod("myfun")
#' #inheritParams myfun
#' #describeIn myfun Create a frequency table from a vector.
#' #export
#' #keywords internal
myfun.default <- function(vec, sort = FALSE, show_na = TRUE, ...) {
...
}
#' #inheritParams myfun.default
#' #describeIn myfun Create a frequency table from a data.frame,
#' supplying the unquoted name of the column to tabulate.
#' #export
#' #keywords internal
tabyl.data.frame <- function(.data, ...){
...
}
(I omitted the #title, #description, #param, #return, #examples lines to keep this question shorter but can edit them in if relevant).
The generic methods are exporting as intended, so that the user only sees myfun() and not myfun.default() or myfun.data.frame(), unless they use the triple colon :::. I'd like to retain that behavior, so the user just calls myfun, while also having an entry for myfun in the package manual.
I removed #keywords internal in the two myfun. methods and that did it: myfun appears in the package's manual. I also switched to #rdname myfun instead of #describeIn myfun, to eliminate the section "Methods (by class):" in the function's documentation.
What made this hard to isolate was that if I run devtools::document() and then don't restart the session, the methods myfun.data.frame and myfun.default are visible in RStudio's autocomplete and can be called directly. They are not supposed to be accessible to the user, and I thought my Roxygen2 documentation was to blame.
In fact, all I had to do was remove #keywords internal.
The methods myfun.data.frame and myfun.default do appear in the autocomplete after typing ?, e.g., ?myfun.default, but I think there's no way around that (and it directs to the single help page for all three myfun functions, anyway). This is standard. For example, ?print.aov is a visible help file while print.aov() cannot be called directly.
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.
A simple example is that I have created an extension to show, which is a S4 base method. I don't want to cause a disambiguation fork by re-documenting show in my package, and I also want to consolidate the documentation of my extension to show in the documentation for the new class, myPkgSpClass, by adding an alias for show,myPkgSpClass-method.
#' #export
#' #aliases show,myPkgSpClass-method
#' #rdname myPkgSpClass-class
setMethod("show", "myPkgSpClass", function(object){ show(NA) })
The problem I'm having, is that this results in an serious warning during documentation-build by roxygen2, Rd files with duplicated alias 'show': because there is more than one class extension to show in this package, and roxygen2 has automatically added the generic term in the list of aliases to all the relevant *-class.Rd files:
\alias{show}
\alias{show,myPkgSpClass-method}
But I think I don't want the generic alias in any of the instances, because it will force the need for disambiguation between show in my package, and the base show. This issue also applies to other S4 methods extended from other packages besides show.
If I tag all class-specific methods to the same .Rd file, then the warning goes away, but the ambiguity remains, because the show alias still gets added automatically for that doc entry. If I manually remove \alias{show} from the .Rd file, then the problem seems solved, no warnings during roxygen or R CMD check pkgname. So how do I get Roxygen2 to not-add the generic alias?
Other background:
This is a specific question building from a previous issue for exporting/documenting S4 extensions to base methods:
Is it necessary to export base method extensions in an R package? Documentation implications?
It is more specific than, and not covered by, the following questions regarding documenting S4 methods / classes using Roxygen2:
How to properly document S4 methods using roxygen2
How to properly document S4 class slots using Roxygen2?
Seems to be fixed in roxygen2_3.1.0:
#' #export
#' #aliases show,myPkgSpClass-method
#' #rdname myPkgSpClass-class
setMethod("show", "myPkgSpClass", function(object){ show(NA) })
produces the myPkgSpClass-class.Rd:
\docType{methods}
\name{show,myPkgSpClass-method}
\alias{show,myPkgSpClass-method}
\usage{
\S4method{show}{myPkgSpClass}(object)
}
\arguments{
\item{object}{Any R object}
}
As Hadley stated, you do not need anymore to explicitly set the alias or the rd name, e.g.:
#' my title
#' #export
setMethod("show", "myPkgSpClass", function(object){ show(NA) })
will generate show-myPkgSpClass-method.Rd:
\docType{methods}
\name{show,myPkgSpClass-method}
\alias{show,myPkgSpClass-method}
\title{my title}
\usage{
\S4method{show}{myPkgSpClass}(object)
}
\arguments{
\item{object}{Any R object}
}
\description{
my title
}
Note that in that case you have to set the description. It will not generate a doc page if the documentation entry is empty.
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.