Контроль, где документация метода идет для простого универсального, скрываясь от индекса пакета

Question

Я пишу пакет R и в основном следую книге Хэдли на эту тему. Я сталкиваюсь с проблемой с методами документирования для простых обобщений, таких как печать, сюжет, голова и хвост. Когда я использую тег @describeIn для управления тем, куда идет документация по методу, я получаю приятную особенность того, что они отображаются в файле справки для основной функции анализа, которая возвращает объект данного класса. Проблема в том, что эти дженерики также отображаются в индексе пакета. Если я добавлю @keywords internal для обобщенных элементов, то они удаляются из индекса пакета, но так же как и основная функция анализа (они находятся в одном файле.R). Если я документирую обобщения в отдельном файле.R, тогда я могу получить контроль над тем, что есть и нет в индексе пакета, но у меня есть две проблемы: основная функция анализа не стоит на первом месте в разделе "Использование" справки. файл; и если добавить @keywords internal для шаблонов это также удаляет функцию анализа из индекса пакета, даже если они документированы (в данном случае) в отдельных файлах. Суть проблемы, кажется, в том, что @keywords internal применяется ко всем функциям в данном файле.R, и, возможно, даже к любой функции, указанной в @describeIn, в то время как @describeIn предназначен для документирования нескольких функций в данном файле.R.

На данный момент у меня есть функция анализа и обобщения в одном и том же файле.R, чтобы контролировать, куда идет документация метода и его порядок в разделе "Использование", но я не использую @keywords internal и оставив индекс загроможденным.

Вот примерный эскиз экспортированной функции анализа:

#' @inheritParams foo
#' @export
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}

И общий:

#' @describeIn seats Print a \code{\link{seats}} output
#' @keywords internal
#' @export
print.judgeit.seats <- function(x,...) print(x$output,...)

Я хочу файл справки для ?seats выглядеть так:

seats(judgeit.object, ...)

## S3 method for class 'judgeit.seats'
print(x, ...)

## S3 method for class 'judgeit.seats'
head(x, ...)

## S3 method for class 'judgeit.seats'
tail(x, ...)

я не хочу print.judgeit.seats, head.judgeit.seatsи т. д., чтобы появиться в индексе пакета, потому что он быстро становится очень загроможденным.

Answer 1

К сожалению, я не знаю ни одного легкого решения того, что вы просите.

Теги и их влияние

@export сделает вашу функцию видимой в глобальной среде. CRAN требует, чтобы вы документировали любые такие функции, которые не являются скрытыми (то есть начинаются с .).

Если вы используете @describeIn или же @rdname, автоматический псевдоним создан. Любой псевдоним создает запись в индексе, но указывает на тот же файл.Rd. Например, добавив

#' @name myfunction
#' @aliases foo foobar` 

создаст foo а также foobar записи в индексе, но обратитесь к myfunction.Rd файл документации. Если вы попытаетесь удалить вручную \alias{} в.Rd файле CRAN будет жаловаться.

@describeIn перечислит функции в порядке их появления в файлах.R (если они задокументированы в нескольких файлах, они перечислены в алфавитном порядке файла.R, затем в порядке их появления). Изменение порядка ваших функций может дать вам то, что вы хотите.

@keywords internal (вместе с @export, заголовок и описание) заставит Roxygen создать файл.Rd, к которому пользователь может получить доступ, используя ?, но не будет виден в индексе (если у вас есть только теги, Roxygen не будет создавать файл.Rd, и вы получите предупреждение, потому что ваша функция не задокументирована).

Если у тебя есть @keywords internal в любой из функций, вызывающих @describeIn, эта функция будет замаскирована из индекса. Это не относится ко всем функциям в файле.R, только к тем, которые являются псевдонимами.

@usage требует, чтобы у вас был псевдоним для каждого документированного метода. Вы можете попробовать использовать вместо @section Usage:, но разделы заметок перечислены в алфавитном порядке, и интервал будет больше.

Временное решение

Если вы документируете NULL функция, вы можете добавить @param ты хочешь. и включать в себя несколько строк @Section: Usage поле для включения (вручную) методов S3 с вашими комментариями. Дайте ему имя, такое как @name Seats (это не может быть имя функции, в противном случае у вас есть ?seats указывая на два разных файла).

Затем документируйте свою функцию seats с другим @name тег и другой заголовок, и использовать @internal' to hide it from the user. Use\code{\link{seat}}`для ссылки на эту документацию.

#' Seats 
#' Description of the function
#' @param judgeit.object object
#' @param x object from seats
#' @param ... additional arguments
#' @name seats
#' @section Usage:
#' \preformatted{seats(judgeit.object, ...)
#' ## S3 method for class 'judgeit.seats'
#' print(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' head(x, ...)
#' ## S3 method for class 'judgeit.seats'
#' tail(x, ...)}
NULL

#' Seats function
#' @name internal-function
#' @inheritParams seats
#' @export
#' @keywords internal
#' @seealso \code{\link{seats}}
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object) 
}

#' Print a \code{\link{seats}} output
#'
#' @inheritParams seats
#' @describeIn internal-function 
#' @export
print.judgeit.seats <- function(x,...) print(x$output,...)

Таким образом, пользователь звонит ?seats будет указано на общую документацию.