Roxygen2 - comment documenter correctement les méthodes S3

Question

J'ai lu le Roxygen2 PDF ainsi que ce site et je suis perdu sur la différence entre @méthode @S3method @exportation et la façon dont vous utilisez ces documenter correctement S3 méthodes. J'ai travaillé jusqu'le suivre exemple pour la discussion:

1. Comment aurais-je bien documenter ces?

2. Comment puis-je imiter la documentation de l' ?d'impression et d'autres fonctions génériques qui montrent les cas d'utilisation pour tous spécifiques à la classe implimentations (c'est à dire le chemin ?imprimer montre l'utilisation de 'facteur', 'table','fonction')

3. À partir de la page du wiki: "Toutes les méthodes exportées besoin de l' @S3method tag. Il a le même format que @méthode. Cette exportation de la méthode, et non la fonction - c'est à dire générique(monobjet) fonctionnera, mais générique.mymethod(monobjet) ne sera pas."
Je ne peux pas l'interpréter. Ce qui semble dire que la fonction/méthode appels ne fonctionnent pas correctement si les balises sont mal définies? Qu'est-ce qui va casser?

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

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

Answer 1

A partir de roxygen2> 3.0.0, vous avez seulement besoin de @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
}
 

Mais puisque vous ne documentez pas réellement les méthodes, voici ce qui suffit:

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

L' @method balise génère \entrées de méthode dans l' \champ utilisation en Rd fichiers.

L' @S3method balise génère S3method() les entrées dans le fichier d'espace de NOMS.

L' @export balise génère à l'exportation() les entrées dans le fichier d'espace de NOMS.

Voici mon exemple:

#' 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 à Partir de la page du wiki...

Je suppose que cela signifie que "vous n'écrivez pas de @S3method generic mymethod myobject."