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

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

44 голосов
/ 26 августа 2011

Я прочитал 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
}

Ответы [ 2 ]

58 голосов
/ 24 марта 2014

Начиная с 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
}
36 голосов
/ 26 августа 2011

Тег @method создает записи \ method в поле \ using в файлах Rd.

Тег @S3method создает записи S3method () в файле NAMESPACE.

The *Тег 1007 * генерирует записи 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
}

enter image description here

3 Со страницы вики...

Полагаю, это означает "ты не пишешь @S3method generic mymethod myobject."

...