R 控制方法文档用于简单泛型的位置,同时隐藏包索引
我正在写一个R软件包,主要关注哈德利关于这个主题的书。我在为简单的泛型(如print、plot、head和tail)编写文档方法时遇到了一个问题。当我使用@describeIn标记来控制方法文档的位置时,我会在主分析函数(返回给定类的对象)的帮助文件中看到它们的良好特性。问题是这些泛型也出现在包的索引中。如果我将R 控制方法文档用于简单泛型的位置,同时隐藏包索引,r,packages,devtools,roxygen2,R,Packages,Devtools,Roxygen2,我正在写一个R软件包,主要关注哈德利关于这个主题的书。我在为简单的泛型(如print、plot、head和tail)编写文档方法时遇到了一个问题。当我使用@describeIn标记来控制方法文档的位置时,我会在主分析函数(返回给定类的对象)的帮助文件中看到它们的良好特性。问题是这些泛型也出现在包的索引中。如果我将@keywords internal添加到泛型中,那么它们将从包的索引中删除,但主分析函数也是如此(它们位于同一个.R文件中)。如果我将泛型记录在一个单独的.R文件中,那么我可以控制包索
@keywords internal
添加到泛型中,那么它们将从包的索引中删除,但主分析函数也是如此(它们位于同一个.R文件中)。如果我将泛型记录在一个单独的.R文件中,那么我可以控制包索引中的内容和内容,但我有两个问题:主分析函数在帮助文件的用法部分不是第一位的;如果为泛型添加@keywords internal
,这也会从包索引中删除分析函数,即使它们(在本例中)记录在单独的文件中。问题的症结似乎在于@keywords internal
适用于给定.R文件中的所有函数,甚至可能适用于@descripebein
中引用的任何函数,而@descripebein
旨在记录给定.R文件中的多个函数
目前,我在同一个.R文件中使用了分析函数和泛型来控制方法文档的位置及其在用法部分中的顺序,但我没有使用@关键字internal
,并使索引杂乱无章
下面是导出的分析函数的草图:
#' @inheritParams foo
#' @export
seats <- function(judgeit.object, ...) {
[...omitted...]
class(out.object) <- "judgeit.seats"
return(out.object)
}
我不希望
打印.judgeit.seats
,头.judgeit.seats
等出现在包索引中,因为它很快就会变得非常混乱 不幸的是,我不知道有什么简单的方法可以解决你的问题
标签及其效果
@export
将使您的功能在全局环境中可见。CRAN要求您记录任何未隐藏的功能(即以
开头的功能)
如果使用@descripbein
或@rdname
,将创建一个自动别名。任何别名都会在索引中创建一个条目,但指向相同的.Rd文件。例如,添加
#' @name myfunction
#' @aliases foo foobar`
将在索引中创建foo
和foobar
项,但请参阅myfunction.Rd
文档文件。如果您试图手动删除.Rd文件中的\alias{}
,CRAN会抱怨
@descripbein
将按函数在.R文件中的显示顺序列出函数(如果它们在多个文件中记录,则按.R文件的字母顺序列出,然后按出现顺序列出)。重新排序函数可以满足您的需要
@keywords internal
(连同@export
、标题和说明)将让Roxygen创建一个.Rd文件,用户可以使用?
访问该文件,但在索引中不可见(如果您只有标签,Roxygen将不会创建.Rd文件,并且您将收到警告,因为您的函数没有文档记录)
如果在调用@descripebein
的任何函数中有@keywords internal
,则该函数将从索引中屏蔽。这并不适用于.R文件中的所有函数,仅适用于别名函数
@usage
要求每个方法都有一个别名。您可以尝试改用@section usage:
,但请注意,节是按字母顺序列出的,间距会更大
变通办法
如果您记录了一个NULL
函数,您可以添加所需的@param
。并包括多行@部分:用法
字段,以(手动)包含S3方法和注释。给它一个名称,例如@name Seats
(它不能是函数的名称,否则您的?seats
指向两个不同的文件)
然后,使用不同的@name
标记和不同的标题记录函数seats
,并使用@internal'对用户隐藏它。使用\code{\link{seats}}`引用该文档
#' 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,...)
#“座位
#'功能说明
#“@param judgeit.object对象
#“@param x对象来自座椅
#“@param…其他参数
#“@name座位
#“@节用法:
#'\preformatted{seats(judgeit.object,…)
###S3类“判断座位”的方法
#'打印(x,…)
###S3类“判断座位”的方法
#'头(x,…)
###S3类“判断座位”的方法
#'尾(x,…)}
无效的
#“座椅功能
#'@name内部函数
#"他的座位
#“@出口
#“@关键字内部
#“@see也\code{\link{seats}”
程序包索引中的函数几乎总是按字母顺序排序的。我不知道是否有其他顺序。
#' @name myfunction
#' @aliases foo foobar`
#' 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,...)