如何使用 roxygen 记录包含同名函数的 R 包?

How do I use roxygen to document a R package that includes a function with the same name?

我正在学习使用氧气。我看到 rd vignette 提倡使用“_PACKAGE”来表示我正在创建包文档,并说 "This also works if there’s already a function called pkgname()."

我也看到了 R packages book 使用

的方法
NULL

指定了@docType 和@name,但是当我尝试用这两种方法制作玩具示例时,它并没有像我预期的那样工作。

作为玩具示例,我想制作一个包含 "hello()" 功能的 "hello" 包。

我希望得到关于我的 hello package

的文档
?hello

或者类似

package?hello

并且我希望获得有关包含的 hello 函数

的文档
?hello()

我哪里错了? - 使用 roxygen 实施、我尝试查询文档的方式、不正确的期望或其他?

我已经看过关于 and function documentation 的问题,但我仍然不清楚。

以下是关于我的玩具示例的一些详细信息:

hello/DESCRIPTION 文件:

Package: hello
Type: Package
Title: A mostly empty package
Version: 0.1
Date: 2016-06-21
Authors@R: person("Some", "Person", email = "fake@madeup.org", role = c("aut", "cre"))
Description: More about what it does (maybe more than one line)
License: MIT
LazyData: TRUE
RoxygenNote: 5.0.1.9000

hello/R/hello.R

#' hello
#'
#' This is a mostly empty package to learn roxygen documentation.
#'
#' Hello allows me to learn how to write documentation in comment blocks
#' co-located with code.
#' @docType package
#' @name hello
"_PACKAGE"

#' hello
#'
#' This function returns "Hello, world!".
#' @export
#' @examples
#' hello()

hello <- function() {
  print("Hello, world!")
}

这样,我运行document()后,hello/man/hello.Rd就生成了。它包含我为 hello 包和 hello() 函数编写的描述的组合。 ?hello?hello() 都 return 那个 .Rd 文件。

这是 .Rd 的样子:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hello.R
\docType{package}
\name{hello}
\alias{hello}
\alias{hello-package}
\title{hello}
\usage{
hello()
}
\description{
This is a mostly empty package to learn roxygen documentation.

This function returns "Hello, world!".
}
\details{
Hello allows me to learn how to write documentation in comment blocks
co-located with code.
}
\examples{
hello()
}

来自@hadley,"don’t use @ name hello. That overrides default naming" 和 "sometimes you need to restart R because there’s something buggy with devtools and dev docs"

因此,如果我将 hello.R 文件更改为:

#' hello
#'
#' This is a mostly empty package to learn roxygen documentation.
#'
#' Hello allows me to learn how to write documentation in comment blocks
#' co-located with code.
"_PACKAGE"

#' hello
#'
#' This function returns "Hello, world!".
#' @export
#' @examples
#' hello()

hello <- function() {
  print("Hello, world!")
}

然后 document() 生成 hello-package.Rd 和 hello.Rd 文件。在我加载 library(hello) 之后,然后 package?hello 提供包文档,而 ?hello 提供功能文档,正如我所追求的!

再次感谢@hadley!

正如 Johan Larsson 和 brendan 在对 的评论中指出的那样,该函数的别名似乎被包覆盖了。

提到了一个解决方案here and here。就是加上@aliases {pkgname}-package(这里是@aliases hello-package)。

我看到它反复说你需要添加@aliases {pkgname}-package,但我不清楚它是在hello函数注释块还是在package doc块中。

剧透警告:它在包文档块中:

#' hello
#'
#' This is a mostly empty package to learn roxygen documentation.
#'
#' Hello allows me to learn how to write documentation in comment blocks
#' co-located with code.
#' @aliases hello-package
"_PACKAGE"

#' hello
#'
#' This function returns "Hello, world!".
#' @export
#' @examples
#' hello()

hello <- function() {
  print("Hello, world!")
}