R包里的帮助文档是怎么写的

2020-03-05 本文已影响0人小洁忘了怎么分身

花花写于2020-3-5

本文是《R包开发》第5章的学习记录，讲述帮助文档写法。

R包开发时需要写的文档，就是使用者可以用？和help调用的帮助文档了。
R包里有一个man文件夹，包含.Rd文件，和R/函下的函数对应。这些文件不需手写，使用roxygen2 包自动生成。
roxygen2 在生成 .Rd 文件的同时，还可以管理 NAMESPACE 和 DESCRIPTION 中的 Collate 域。

1.文档工作流程

(1) 添加 roxygen 注释到 .R 文件。
(2)运行 devtools::document()(或在 RStudio 中按 Ctrl/Cmd+Shift+D)将 roxygen 注释转为 .Rd 文件。
(这一步也可换成Ctrl/Cmd+Shift+B，表示编译并重启r包)
(3) ? 预览文档。
(4) 修改注释，重复上面这些步骤，直到文档变成你想要的样子。

2. roxygen 注释

格式：

#' Add together two numbers. 
#'
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}. 
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) { x+ y
}

第一段是标题，第二段是discription，第三段是details（可选）。段落之间用仅有#'的行隔开。
@开头的是tagname。
@section 添加自定义标签，格式：

#' @section Warning:
#' Do not operate heavy machinery within 8 hours of using this function.

@seealso 可以指向其他有用的资源，例如其他函数或者网址。
@family同族函数
@aliases 别名1 别名2
@keywords关键词1 关键词2
仿写了一段

#' count unique values in every colunms for data.frame
#'
#' simplify pdata, delete columns with unique values,which can't be used as group vector
#' @usage dumd(x = iris)
#' @param x A data.frame.
#' @return The simple data.frame of columns unique values count in \code{x}
#' @examples
#' dumd(iris)
#' data(ToothGrowth)
#' x = ToothGrowth
#' dumd(ToothGrowth)
#' @section just :
#' See what are you doing

dumd <- function(x){
  colname <- vector("character")
  count <- vector("integer")
  for(i in 1:ncol(x)){
    colname[i] = colnames(x)[[i]]
    count[i]=nrow(x[!duplicated(x[,i]),])
  }
  df <- tibble(colname,count) %>%
    arrange(desc(count))
  print(df)
}

预览：

3.函数文档

常见的三个标签：@param、@example和 @return。
@param一行可写多个参数，用逗号隔开：

#' @param x,y A data.frame.

@example 示例代码，必须保证没有错误
@return 返回值描述
补充：@usage 列出有哪些参数，默认参数是什么，是自动生成的。

插曲：如果代码里包含扩展包里的函数，需要用@importFrom 指定，@export输出，我是从Y叔的github看的，毕竟clusterProfiler有那么多依赖包，肯定写了。但是我一开始只看到了importFrom，不知道export，就出错了。报错信息非常令人困扰，查无可查，因为它说“找不到函数”，你妹呀，我在开发包，我自己写的函数，你告诉我找不到。。。我找到曾老板和Y叔写的包，对着看。我不想承认我排查了三个半小时，才找到了问题所在。这个博客写的挺好：
https://tinyheero.github.io/jekyll/update/2015/07/26/making-your-first-R-package.html

##' @importFrom FactoMineR PCA
##' @importFrom factoextra fviz_pca_ind
##' @export

包的文档和数据集的文档会在后面的章节介绍。

4.避免无效重复

方案1：继承其他函数的参数

@inheritParams重用参数文档，即从其他函数中继承参数的文档，格式：

#' @param a This is the first argument foo <- function(a) a + 10
#' @param b This is the second argument 
#' @inheritParams foo 
bar <- function(a, b) {foo(a) * 10 }

# 等价于:
#' @param a This is the first argument 
#' @param b This is the second argument 
bar <- function(a, b) {foo(a) * 10 }

重点就是#' @inheritParams foo那一行。

方案2：多个函数的文档写在一起

通常是一些参数相似的函数，或者有互补性的函数。
使用rdname将add和times两个函数写在一起的例子：

#' Basic arithmetic
#'
#' @param x,y numeric vectors.
add <- function(x, y) x + y
#' @rdname add
times <- function(x, y) x * y

这次是自动自动生成的Usage，两个函数都有。?add和?times都可调用该页面。大概明白了read.table和read.csv是怎么写到一起的啦.

4.文本格式

包括字符格式：粗体、斜体、代码、链接、列表、数学符号、表格等。摘录三个我以后会常用的：

\strong{bold}
\code{}
\link[=dest]{name}

最后一个表示链接到 dest，显示为 name

我的小辣鸡R包已经初具雏形了，里面有4个根据我的审美来美化的画图函数（PCA图，火山图，热图和韦恩图）和一个数据框统计函数，今天没课，尽情研究了一天，等我优化一下再来发个推文！