Comment documenter correctement une méthode S3 d'un générique d'un package différent, en utilisant Roxygen?

Question

Je suis en train d'écrire un package qui définit une nouvelle classe, arpenteur-géomètre, et un print méthode pour cela, print.surveyor. Mon code fonctionne très bien et je l'utilise roxygen en ligne de la documentation. Mais R CMD check émet un avertissement:

Fonctions/méthodes d'utilisation dans la documentation de l'objet à imprimer.arpenteur' mais pas dans le code: imprimer

J'ai utilisé les deux pages suivantes, écrites par le Hadley, comme source d'inspiration: Les espaces de noms et de Documentation des fonctions, qui stipule que la syntaxe correcte est - @method function-name class

Donc ma question est: Quelle est la façon correcte de la documentation de l' print méthode pour ma nouvelle classe à l'aide de Roxygen? Et plus précisément, comment se débarrasser de l'avertissement?

---

Voici mon code: (Le commentaire de la documentation indiquée tentatives de fixation de ce, aucun n'a fonctionné.)

#' 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)
}

Et le roxygenized de sortie, c'est à dire 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}}

Answer 1

La fonction doit être documentés à l' @method balise:

#' @method print surveyor

Sur la première lecture, @hadley du document a été un peu difficile pour moi car je ne suis pas familier avec roxygen, mais après plusieurs lectures de l'article, je pense que je comprends la raison pourquoi vous avez besoin d' @method.

Vous êtes à la rédaction de la documentation complète pour l' print méthode. @S3method est liée à l' NAMESPACE et s'occupe de la méthode à l'exportation. @S3method n'est pas fait pour de la documentation d'une méthode.

Votre Rd fichier doit comporter les éléments suivants dans l' usage section:

\method{print}{surveyor}(x, ...)

si cela fonctionne correctement, que c'est la bonne façon de documenter S3 méthodes en Rd fichiers.

Answer 2

À partir de roxygen2> 3.0.0., Vous n’avez besoin que de @export car il peut déterminer que print.surveyor est une méthode S3. Cela signifie que vous n'avez plus besoin que de

 #' Prints surveyor object.
#' 
#' @param x surveyor object
#' @param ... ignored
#' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}
 

Cependant, dans ce cas, la documentation n'étant pas très utile, il vaudrait probablement mieux faire:

 #' @export
print.surveyor <- function(x, ...){
    cat("Surveyor\n\n")
    print.listof(x)
}