rroxygen

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


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

Solution

  • 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)
    }