How to properly document a S3 method of a generic from a different package, using Roxygen?

registering s3 methods
how to use roxygen2
roxygen2 requires encoding: utf-8
roxygen2 cheat sheet
roxygen tags
create r package roxygen2
warning: the existing 'namespace' file was not generated by roxygen2, and will not be overwritten.
how to use importfrom in roxygen2

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

Object documentation � R packages, 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� Generally, it’s not necessary to document straightforward methods for common generics like print(). (You should, however, always @export S3 methods). If your method is more complicated, you should document it by setting @rdname. Typically you will document methods with their generic, so you’d document foofy.data.frame by setting @rdname.


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.

`document` generates wrong S3 exports if NAMESPACE doesn't , Instead of writing these files by hand, we're going to use roxygen2 which It abstracts over the differences in documenting different types of objects, so you need to learn fewer details. This is a generic function: methods can be defined for it directly or via the S3 generics are regular functions, so document them as such. S3 methods are printed by pasting the generic function and class together, separated by a ‘.’, as generic.class. The S3 method name is followed by an asterisk * if the method definition is not exported from the package namespace in which the method is defined.


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

Rd (documentation) tags, However, the roxygen2 tags inside my package are correct: #' @importFrom roxygen2 roclet_tags As a consequence, even though the Imports are correctly listed in the DESCRIPTION , devtools fails to import the necessary S3 generic which my method extends. Add a new file R/test.r with the contents. S3 methods in the R programming language are a way of writing functions in R that do different things for objects of different classes. S3 methods are so named as the methods shipped with the release of the third version of the “S” programming language, which R was heavily based upon [@chambers1992, @rclassmethods, @R].


Generating Rd files, Text within roxygen blocks can be formatted using markdown or Rd This is a generic function: methods can be defined for it directly #' or via the [Summary()] group generic. put them in separate files and use @example path/relative/to/ package/root to insert S3 generics are regular functions, so document them as such. How to properly document S4 “[” and “[<-“ methods using roxygen? How to properly document a S3 method of a generic from a different package, using Roxygen? Roxygen2-how to properly document S3 methods ; How to properly document S4 methods using roxygen2


roxygen2 2.2, With roxygen2, there are few reasons to know about Rd files, so here I'll avoid discussing them This is a generic function: methods can be defined for it directly #' or via the put them in separate files and use @example path/relative/ to/package/root to insert S3 generics are regular functions, so document them as such. In this case, roxygen requires quite strict conventions for function exporting. We have found that in practice it is next to impossible to dynamically assign S3 generics and methods to the package environment and successfully document the generics/methods in a way that allows I) correct documentation and II) the correct methods exported.


roxygen2 2.2, The default @inherit my_fun will inherit all, you can document an object Non- primitive, internal S3 generics (e.g. 'rbind', 'cbind') are now properly detected as S3 generics. S3 method declarations via R.methodS3::setMethodS3() and function and now exported making it possible to create roclets in other packages. 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.