example - roxygen importfrom

Roxygen2-cómo documentar adecuadamente los métodos S3

Question

He leído el PDF de Roxygen2 así como este site y estoy perdido sobre la diferencia entre @method @ S3method @export y cómo los usa para documentar adecuadamente los métodos de S3. Trabajé el siguiente ejemplo para discusión:

1. ¿Cómo puedo documentar adecuadamente estos?

2. ¿Cómo emulo la documentación de? Print y otras funciones genéricas que muestran los casos de uso para todas las implementaciones específicas de la clase (es decir, la forma? Print muestra el uso de ''factor'', ''tabla'', ''función'')

3. Desde la página wiki: "Todos los métodos exportados necesitan la etiqueta @ S3method. Tiene el mismo formato que @method. Esto exporta el método, no la función, es decir, genérico (myobject) funcionará, pero generic.mymethod (myobject) no lo hará ".
No puedo interpretar esto. ¿Parece que las llamadas de función / método no funcionarán correctamente si las etiquetas no se especifican correctamente? ¿Qué se romperá específicamente?

MyHappyFunction = function( x , ... )
{
    UseMethod( "MyHappyFunction" )
}

MyHappyFunction.lm = function( x , ... )
{
  # do some magic
}

Answer 1

A partir de roxygen2> 3.0.0, solo necesita @export :

#'' A description of MyHappyFunction
#''
#'' A details of MyHappyFunction
#''
#'' @title MyHappyFunction: The my happy function
#'' @param x numeric number
#'' @param ... other arguments
#'' @examples
#'' a <- 1
#'' class(a) <- "lm"
#'' MyHappyFunction(a)
#'' @export
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#'' @rdname MyHappyFunction
#'' @export
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#'' @rdname MyHappyFunction
#'' @export
MyHappyFunction.default = function(x, ...) {
  # do some magic
}

Pero como en realidad no está documentando los métodos, lo siguiente es suficiente:

#'' A description of MyHappyFunction
#''
#'' A details of MyHappyFunction
#''
#'' @title MyHappyFunction: The my happy function
#'' @param x numeric number
#'' @param ... other arguments
#'' @examples
#'' a <- 1
#'' class(a) <- "lm"
#'' MyHappyFunction(a)
#'' @export
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#'' @export
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#'' @export
MyHappyFunction.default = function(x, ...) {
  # do some magic
}

Answer 2

La etiqueta @method genera / las entradas de método en el campo / use en los archivos Rd.

La etiqueta @S3method genera entradas S3method () en el archivo NAMESPACE.

La etiqueta @export genera entradas de exportación () en el archivo NAMESPACE.

Aquí está mi ejemplo:

#'' A description of MyHappyFunction
#''
#'' A details of MyHappyFunction
#''
#'' @title MyHappyFunction: The my happy function
#'' @param x numeric number
#'' @param ... other arguments
#'' @examples
#'' a <- 1
#'' class(a) <- "lm"
#'' MyHappyFunction(a)
#''
#'' @rdname MyHappyFunction
#'' @export MyHappyFunction
MyHappyFunction <- function(x, ...){
  UseMethod("MyHappyFunction")
}

#'' @return /code{NULL}
#''
#'' @rdname MyHappyFunction
#'' @method MyHappyFunction lm
#'' @S3method MyHappyFunction lm
MyHappyFunction.lm = function(x, ...) {
  # do some magic
}

#'' @return /code{NULL}
#''
#'' @rdname MyHappyFunction
#'' @method MyHappyFunction default
#'' @S3method MyHappyFunction default
MyHappyFunction.default = function(x, ...) {
  # do some magic
}

3 De la página wiki ...

Supongo que significa "no escribes @S3method generic mymethod myobject ".