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

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

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

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

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

То, что я пытался сделать, это поместить следующее В funs.R: 

##' @rdname funs
##' @name funs
##' @aliases sum1
##' @aliases prod1
##' @title Two functions
##' @param x X
##' @param y Y
##' @return sum1 returns x+y
##' cr
##' prod1 returns x*y
##' @examples
##' sum1(3,4)
##' prod1(3,4)
##' @export
sum1 <- function(x,y) x+y
##' @export
##' @rdname funs
prod1 <- function(x,y) x*y

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

##' @export
funs <- function(x) x

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

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

Также, на родственной обратите внимание, делает ли что-то Normal?

require(stats)
getAnywhere("Normal")
> no object named 'Normal' was found

Обновление:

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

##' sum
##' gives the sum
##' @param x X
##' @param y Y
##' @return sum1 returns x+y
##' @examples
##' sum1(3,4)
##' @rdname funs
##' @export
sum1 <- function(x,y) x+y
##' product
##' gives the product
##' @return prod1 returns x*y
##' @examples
##' prod1(3,4)
##' @rdname funs
##' @export
prod1 <- function(x,y) x*y

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

Возможно, это просто невозможно...
2 39
documentation roxygen2

2 ответа:

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

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

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

21

Насколько я понимаю, единственный способ, чтобы 3 имени были задокументированы в вашем .Файл РД-это документ 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
Это выглядит довольно банально, но это работает.
17