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}}
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
.
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.