Roxygen2 - как правильно документировать методы S3

Я прочитал Roxygen2 PDF, а также этот сайт, и я потерял разницу между @method @S3method @export и как вы их используете, чтобы правильно документировать методы S3. Я рассмотрел следующий пример для обсуждения:

1. Как я должен правильно документировать эти данные?

2. Как я могу подражать документации на печать и другие общие функции, которые показывают примеры использования для всех специфических для класса специфических внедрений (т.е. Путь? Print показывает использование для "фактора", "таблицы", "функции" )

3. На странице wiki: "Все экспортированные методы нуждаются в теге @S3method. Он имеет тот же формат, что и @method. Это экспортирует метод, а не функцию - то есть общий (myobject), но generic.mymethod(myobject) не будет".
Я не могу это интерпретировать. Это говорит о том, что вызовы функции/метода не будут работать должным образом, если теги будут неправильно указаны? Что конкретно сломается?

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

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

Ответ 1

Тег @method генерирует записи \method в поле \use в файлах Rd.

Тег @S3method генерирует записи S3method() в файле NAMESPACE.

Тег @export генерирует записи export() в файле NAMESPACE.

Вот мой пример:

#' 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 На странице wiki...

Я предполагаю, что это означает "вы не пишете @S3method generic mymethod myobject".

Ответ 2

Как и для roxygen2 > 3.0.0, вам нужно только @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
}

Но поскольку вы на самом деле не документируете методы, достаточный:

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