r - 在 R 中使用支持函数保持 DRY 的最佳方法

Question

在处理我的第一个 R 包时，a 注意到当在 man 目录“man”中创建包结构时，代码中的每个函数/方法都有一个文档文件。

为了保持干燥（不要重复自己），我在循环或迭代中使用了一些函数作为“辅助”函数。我怎么能告诉 R 我不想为他们提供任何文档，因为最终用户不应该直接调用它们？！？！

Answer 1

Use the roxygen2 and devtools packages to document your functions and build your package.

#' Function 1 Title
#'
#' Describe what function 1
#' does in a paragraph. This function
#' will be exported for external use because
#' it includes the @export tag.
#'
#' @param parameter1 describe the first parameter
#' @param parameter2 describe the second parameter
#' @examples
#' function1(letters[1:10], 1:10)
#' @export
function1 <- function(parameter1, parameter2) {
  paste(parameter1, parameter2)
}

#' Function 2 Title
#'
#' Description here. This will not 
#' be added to the NAMESPACE.
#'
#' @param parameter1
function2 <- function(parameter1) {
  parameter1
}

Once you have all your documentation, use the tools in the devtools package to build, document, and check your package. It will automatically update the man files and DESCRIPTION, and add / remove functions from the NAMESPACE.

document()
build()
check()

I also recommend using the rbundler package to control how you load packages.

Answer 2

如果您不通过 NAMESPACE 导出它们，则不需要提供文档。

另一个（旧的）太简单了，比如创建一个，internal.Rd然后定义一堆\alias{foo}, \alias{bar}, \alias{frob}，这样 codetools 也很高兴。

Answer 3

谢谢@Jojoshua-ulrich 和@dirk-eddelbuettel

根据“编写 R 扩展”：

man 子目录应该（仅）包含 R 文档 (Rd) 格式的包中对象的文档文件。文档文件名必须以 ASCII（小写或大写）字母或数字开头，并具有扩展名 .Rd（默认）或 .rd。此外，名称必须在 'file://' URL 中有效，这意味着 9 它们必须完全是 ASCII 并且不包含 '%'。有关更多信息，请参阅编写 R 文档文件。请注意，包中的所有用户级对象都应记录在案；如果包 pkg 包含仅供“内部”使用的用户级对象，它应该提供一个文件 pkg-internal.Rd 记录所有此类对象，并明确说明这些对象不应该由用户调用。例如，请参阅 R 发行版中的 package grid 的源代码。

顺便说一句，是否有任何约定可以在代码中包含注释，以便人们直接从代码中获取函数描述、参数描述等？