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

Question

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

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

2. Как мне эмулировать документацию? Print и другие универсальные функции, которые показывают варианты использования для всех специфических для класса имплиментаций (т.е. способ? Print показывает использование для 'factor', 'table', 'function')

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

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

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

Answer 1

@method тег генерирует записи \method в поле \ использовании в файлах 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 Со страницы вики...

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

Answer 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
}