Несколько функций в одном файле .Rd

Краткая версия. Можно ли эмулировать документацию Normal в пакете stats с помощью roxygen?

Длинная версия. Я работаю над пакетом и пытаюсь сделать документацию более удобочитаемой, имея ряд функций с общими входами/параметрами, собранными под одним заголовком, который будет общей ссылкой к группе. Каждая функция должна быть доступна конечному пользователю независимо.

Я принял во внимание документацию для Normal, которая дает ряд методов, связанных с нормальным распределением, например. stats::dnorm().

Когда я ищу ?dnorm, я нахожу, что имя раздела справки Normal, хотя Normal не является экспортируемой функцией или объектом.

То, что я пробовал, помещает следующее в funs.R:

Затем я запустил roxygen2 выше. Трудность заключается в том, что при запуске R CMD check в этом минимальном пакете он обнаруживает, что пакет не может быть загружен как undefined exports: funs. Если я удалю строку ##' @name funs, пакет пройдет R CMD check, но имя раздела справки sum1, а не funs. Если я добавлю следующий ниже раздел примеров:

Он проходит, и я могу видеть, как отформатирована помощь, как хотелось бы, но я экспортирую бессмысленную функцию, чтобы правильно отобразить имя.

Я попробовал посмотреть в справочных файлах источника для stats, чтобы узнать, как это было достигнуто, но они находятся в формате .Rdx, который я не уверен, как отображать.

Кроме того, в соответствующей заметке, какая вещь Normal?

@TylerRinker - Боюсь, это было первое, что я пробовал. Это объединяет функции в один файл .Rd, но имя связанной справки совпадает с именем первой функции, чего я пытался избежать:

@Andrie - это решение вызывает точно такую же сложность, имя справки совпадает с именем первой функции.

Ответы

Ответ 1

Это лучшее обходное решение, которое я нашел, но буду рад изменить принятый ответ, если что-то лучше появится...

##' @name funs
##' @aliases sum1
##' @aliases prod1
##'
##' @title Two functions of x and y
##'
##' @param x =X
##' @param y =Y
##'
##' @note \code{funs} is a generic name for the functions documented.
##' \cr
##' If called, \code{funs} returns its own arguments.
##'
##' @rdname funs
##' @export
funs <- function(x,y) {identity(c(x,y))}
##'
##' @rdname funs
##' @return \code{sum1(x,y)} returns x+y
##' @examples
##' sum1(3,4)
##' @export
sum1 <- function(x,y) x+y
##'
##' @rdname funs
##' @return \code{prod1(x,y)} returns x*y
##' @examples
##' prod1(3,4)
##' @export
prod1 <- function(x,y) x*y

Обратите внимание, что форматирование позволяет избежать использования @usage, чтобы избежать появления отчетной ошибки.

Я вижу, как это лучше было бы адресовать на github.

Лучшим решением, использующим @usage, является добавление следующей строки:

##' @usage funs(x,y) A nominal function of x and y

после первого использования

##' @rdname funs
##' @export

Однако я пытаюсь минимизировать "нет". предупреждений, брошенных R CMD check, чтобы успокоить полномочия, которые есть, в частности следующее:

 Functions with \usage entries need to have the appropriate \alias
    entries, and all their arguments documented.
    The \usage entries must correspond to syntactically valid R code.

Последнее может быть ошибкой моего чтения документации для @usage.

Большое спасибо.

Ответ 2

Насколько я понимаю, единственный способ иметь 3 имени, задокументированных в вашем .Rd файле, состоит в том, чтобы документировать 3 реальных объекта, как вы это делали. Но трюк: один из них может быть NULL и не экспортироваться!

##' @name funs
##' @rdname funs
##'
##' @title Two functions of sum1 and prod1
##'
##' @param x =X
##' @param y =Y
##'
##' @return x*y (prod1) or x+y (sum1).
NULL

##' @rdname funs
##' @examples
##' sum1(3,4)
##' @export
sum1 <- function(x,y) x+y

##' @rdname funs
##' @examples
##' prod1(3,4)
##' @export
prod1 <- function(x,y) x*y

Он выглядит довольно взломанным, но он работает.