example - roxygen2 documentation data

¿Cómo documentar correctamente un método S3 de un genérico de un paquete diferente, utilizando Roxygen?

Question

Estoy escribiendo un paquete que define una nueva clase, topógrafo y un método de print para esto, es decir, print.surveyor . Mi código funciona bien y uso roxygen para la documentación en línea. Pero R CMD check emite una advertencia:

Funciones / métodos con uso en el objeto de documentación ''print.surveyor'' pero no en código: print

He utilizado las siguientes dos páginas, escritas por Hadley, como inspiración: Funciones de Namespaces y Documentación , que establecen que la sintaxis correcta es @method function-name class

Entonces mi pregunta es: ¿Cuál es la forma correcta de documentar el método de print para mi nueva clase usando Roxygen? Y más específicamente, ¿cómo me deshago de la advertencia?

Aquí está mi código: (La documentación comentada indicó intentos de arreglar esto, ninguno de los cuales funcionó).

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

Y la salida roxygenizada, es decir 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

Actualizar

A partir de roxygen2> 3.0.0, el paquete se ha vuelto mucho más inteligente para entender todo esto. Ahora solo necesita la etiqueta @export y roxygen resolverá qué tipo de cosas está documentando y hará lo correcto al escribir el NAMESPACE etc., durante la conversión.

Hay excepciones en las que es posible que necesite ayudar a roxygen . Un example que utiliza Hadley Wickham en su libro de R Paquetes es all.equal.data.frame . Hay ambigüedad en el nombre de esa función en cuanto a qué es la clase y cuál es la función genérica ( all , all.equal , o all.equal.data )?

En tales casos, puede ayudar a roxygen informando explícitamente el genérico y clase / método, por ejemplo

@method all.equal data.frame

La respuesta original a continuación explica más sobre el comportamiento anterior si necesita usar explícitamente @method .

Original

La función debe estar documentada con la etiqueta @method :

#'' @method print surveyor

En la lectura inicial, el documento de @ hadley fue un poco confuso para mí, ya que no estoy familiarizado con roxygen , pero después de varias lecturas de la sección, creo que entiendo la razón por la cual necesita @method .

Está escribiendo la documentación completa para el método de print . @S3method está relacionado con NAMESPACE y organiza el método para exportar. @S3method no está diseñado para documentar un método.

Su archivo Rd debe tener lo siguiente en la sección de usage :

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

si esto funciona correctamente, ya que esa es la forma correcta de documentar los métodos S3 en los archivos Rd.

Answer 2

A partir de roxygen2> 3.0.0., Solo necesitas @export porque roxygen puede deducir que print.surveyor es un método S3. Esto significa que ahora solo necesitas

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

Sin embargo, en este caso, dado que la documentación no es muy útil, probablemente sería mejor hacerlo:

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