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
Related
I am writing a package named foo that defines an S3 class named foo with various S3 methods. I have written a constructor function foo() that returns a foo object. It seemed practical to name the class after the package, and the function after the class, and I hoped that:
package?foo would bring up the package help page.
?foo and ?foo::foo would bring up the function help page.
But what happens is that:
Both package?foo and ?foo bring up the package help page.
Only ?foo::foo brings up the function help page.
Is there a way to give a package and a function the same name that produces my desired behaviour?
Currently I have a file foo_package.R like this:
#' The foo package
#'
#' A very useful package.
#'
#' #docType package
#' #name foo
NULL
and a file foo.R like this:
#' The foo function
#'
#' A very useful function.
#'
#' #param x A data frame.
#' #return A foo object.
#' #export
foo <- function(x) {
structure(x, class = c("foo", "data.frame"))
}
Any hints are appreciated...
Following the second link in #MrFlick's comment, which points to the text under "Packages" in vignette("rd"), I was able to get the expected behaviour.
foo.R is unchanged, but foo-package.R now reads:
#' The foo package
#'
#' A very useful package.
#'
#' #docType package
#' #keywords internal
#' #aliases foo-package
"_PACKAGE"
Now, as desired:
package?foo and ?"foo-package" bring up the package help.
?foo and ?foo::foo bring up the function help.
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 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.