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

Question

我正在学习使用氧气。我看到 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()
}

Answer 1

来自@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！

Answer 2

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

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

Answer 3

我看到它反复说你需要添加@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!")
}

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

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

r

roxygen2

roxygen