17.6　为包撰写文档

把函数的帮助页面放在不同目录的最大的问题是很容易使内容不同步。这方面的一个典型例子是当你要添加、删除或重命名函数参数时。 R不能自动更改相应的帮助文件来匹配函数的更改，你必须同时修改两个文件才能确保它们之间能一直保持更新同步。

roxygen2包通过让你在R的代码注释中直接使用帮助文本解决了这个问题。它还能通过使用一个简单的标记语言，大大减少了对LaTeX知识的依赖。roxygen2继承自Doxygen，它是一个能生成类似C++、C、Java、Fortran、Python和其他语言文档的工具。它的语法非常值得学习，使你能为其他许多语言生成文档。

roxygen2标记的每一行以#'开头。有些部分，如标题和描述，是通过它们在注释段的开始位置来标记。其他部分则以关键字标注。例如，描述返回值的部分使用@return开头来标注。一个完整的帮助文本段如下所示：

  1. #' Help page title 
  2. #' 
  3. #' A couple of lines of description about the function(s). 
  4. #' If you want to include code, use \code{my_code()}. 
  5. #' @param x Description of the first argument. 
  6. #' @param y Description of the second argument. 
  7. #' @return Description of the return value from a function. 
  8. #' If it returns a list, use 
  9. #' \itemize{ 
  10. #' \item{item1}{A description of item1.} 
  11. #' \item{item2}{A description of item2.} 
  12. #' } 
  13. #' @note Describe how the algorithm works, or if the function has 
  14. #' any quirks here. 
  15. #' @author Your name here! 
  16. #' @references Journal papers, algorithms, or other inspiration here. 
  17. #' You can include web links like this 
  18. #' \url{http://www.thewebsiteyouarelinkingto.com} 
  19. #' @seealso Link to functions in the same package with 
  20. #' \code{\link{a_function_or_dataset}} 
  21. #' and functions in other packages with 
  22. #' \code{\link[another_package]{a_function_or_dataset}} 
  23. #' @examples 
  24. #' 
  25. #R code run by the example function 
  26. #' \dontrun{ 
  27. #' 
  28. #R code that isn't run by example or when the package is built 
  29. #' } 
  30. #' @keywords misc 
  31. #' @export f <- function(x, y) 
  32. {
  33.   #Function content goes here, as usual 
  34. }

在上例中，有几件事情需要特别注意。

参数需要使用@parm关键字标注。（术语“parm”在整个Doxygen系统中都是标准的，所以如果想在R中把它改为“arg”会带来更多的混乱，还不如删除它。）@parm参数后面跟着一个空格、参数名、另一个空格，以及参数的描述。

范例中的任何东西都必须是合法的R程序，因为当你构建软件包时它会自动运行。如果你想添加注释，请使用一个额外的哈希符#（在现有的用于roxygen2的#'号顶部）来创建。如果你想补充一些失败情景下（例如演示创建文件时发生错误）的范例，可以把它们包装在一个\dontrun{}块中。

帮助文件可包含关键字，但不是所有关键字都可以。请安装R.oo包来查看所有可能值的列表，并运行此代码片段：

  1. library(R.oo) 
  2. Rdoc$getKeywords()

（或者也可以打开R.home ("doc")返回目录中的KEYWORD的文件。 ）

添加@export关键字将列出NAMESPACE文件中的函数，而这意味着用户应该能够从此包中调用该函数，而不仅仅是一个内部的辅助函数。

整个包的描述文档位于一个名为packagename-package.R的文件中。它类似于函数的文档，但可能更容易撰写，因为它的内容更加少：

  1. #' Help page title. Probably the package name and tagline. 
  2. #' 
  3. #' A description of what the package does, why you might want to use it, 
  4. #' which functions to look at first, and anything else that the user 
  5. #' really, absolutely, must look at because you've created it and it is 
  6. #' astonishing. 
  7. #' 
  8. #' @author You again! 
  9. #' @docType package 
  10. #' @name packagename 
  11. #' @aliases packagename packagename-package 
  12. #' @keywords package NULL

函数文档中有两处位非常重要，一个是@docType package行，它告诉roxygen2这是整个包的文档；另一个是最后的NULL值，它的出现是由于技术的原因——如果你忽略它就会产生错误。

为数据集撰写文档几乎与为整个包撰写文档一样。对此文档的存放位置并没有特定的标准，你可以把它追加到包文档后面，又或者把它放到一个单独创建的packagename-data.R文件中：

  1. #' Help page title 
  2. #' 
  3. #' Explain the contents of each column here in the description. 
  4. #' \itemize{ 
  5. #'    \item{column1}{Description of column1.} 
  6. #'    \item{column2}{Description of column2.} 
  7. #' } 
  8. #' 
  9. #' @references Where you found the data. 
  10. #' @docType data 
  11. #' @keywords datasets 
  12. #' @name datasetname 
  13. #' @usage data(datasetname) 
  14. #' @format A data frame with m rows of n variables NULL

和包一样，对于数据集来说有两处很重要：告诉roxygen2这是函数文档的@docType data行，以及最后的NULL值。

在你为每个函数、数据集和整个包撰写了文档之后，请调用roxygenize函数生成帮助文件以及更新NAMESPACE和DESCRIPTION文件（对于某些更喜欢英式拼写法的人来说，可以使用roxygenize来替代roxygenise）：

  1. roxygenize("path/to/root/of/package")