Актуальный вопрос
Как избежать конфликтов имен файлов Rd при
- S4 generic и его метод не обязательно должны быть определены в одном пакете (пакет, содержащий (некоторые)) настраиваемый метод (ы), зависит от пакета, содержащего общий) и
- используя
roxygenize()из пакета roxygen2 для создания реальных файлов Rd?
Я не уверен, что это проблема roxygen2 или общая проблема, когда общий и их методы разбросаны по пакетам (что ИМХО в целом определенно является реалистичным сценарием для использования, если вы следуете модульный стиль программирования).
Какой рекомендуемый способ справиться с этими ситуациями?
Иллюстрация
В пакете pkga
Предположим, что в пакете pkga вы определили общий метод foo и что вы предоставили соответствующий код roxygen, который roxygenize() выбирает для создания Rd файла:
#' Test function
#'
#' Test function.
#'
#' @param ... Further arguments.
#' @author Janko Thyson \email{[email protected]@rappster.de}
#' @example inst/examples/foo.R
#' @docType methods
#' @rdname foo-methods
#' @export
setGeneric(
name="foo",
signature=c("x"),
def=function(
x,
...
) {
standardGeneric("xFoo")
}
)
Когда roxygenizing() ваш пакет, в подкаталоге man создается файл с именем foo-methods.Rd, который служит в качестве ссылочного Rd файла для всех методов, которые могут быть созданы для этого общего метода. Все идет нормально. Если все методы этого родословного также являются частью вашего пакета, все хорошо. Например, этот код-роуд-код будет обеспечивать добавление документации к foo-methods.Rd для ANY -метода foo:
#' @param x \code{ANY}.
#' @return \code{TRUE}.
#' @rdname foo-methods
#' @aliases foo,ANY-method
#' @export
setMethod(
f="foo",
signature=signature(x="ANY"),
definition=cmpfun(function(
x,
...
) {
return(TRUE)
}, options=list(suppressAll=TRUE))
)
Однако если пакет pkga предоставляет общий для foo и вы решите в каком-то другом пакете (скажем, pkgb) добавить foo -метод для x класса character, тогда R CMD check сообщит вам, что существует столкновение имен в отношении имен файлов Rd и/или псевдонимов (так как в файле pkga уже существует файл Rd foo-methods.Rd):
В пакете pkgb
#' @param x \code{character}.
#' @return \code{character}.
#' @rdname foo-methods
#' @aliases foo,character-method
#' @export
setMethod(
f="foo",
signature=signature(x="character"),
definition=cmpfun(function(
x,
...
) {
return(x)
}, options=list(suppressAll=TRUE))
)
Чтобы быть более точным, это ошибка, которая была отправлена /записана в файл 00install.out
Error : Q:/pkgb/man/foo-methods.Rd: Sections \title, and \name must exist and be unique in Rd files
ERROR: installing Rd objects failed for package 'pkgb'
Due dilligence
Я попытался изменить значения для @rdname и @aliases на foo_pkgb* (вместо foo*), но \title и \name все еще настроены на foo при роугенировании и, следовательно, ошибке остается. Любые идеи помимо ручного редактирования файлов Rd, сгенерированных roxygenize()?
EDIT 2012-12-01
В свете начала щедрости реальный вопрос может получить чуть более широкий вкус:
Как мы можем реализовать некоторую проверку "межпакетов" в отношении файлов Rd и/или как мы можем консолидировать файлы справки по методу S4, разбросанные по пакетам, в один Rd файл, чтобы представить один источник ссылки на конечного пользователя?