花花写于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图，火山图，热图和韦恩图）和一个数据框统计函数，今天没课，尽情研究了一天，等我优化一下再来发个推文！
网友评论