R语言函数文档编写指南

### R语言函数文档编写指南 #### 1. 函数参数文档化 在R语言中，函数参数的文档化至关重要。例如在`str_wrap()`函数里，`indent`和`exdent`分别用于定义首行和后续行的缩进： ```R #' @param indent,exdent A non-negative integer giving the indent for the #' first line (`indent`) and all subsequent lines (`exdent`). ``` 当包中存在许多紧密相关的函数时，这些函数可能会有相同名称和含义的参数。为避免重复复制粘贴`@param`文档，roxygen2提供了`@inheritParams`标签，它允许从另一个函数（甚至是另一个包中的函数）继承参数文档。 以`stringr`包为例，大多数函数都有`string`和`pattern`参数，详细且权威的文档在`str_detect()`函数中： ```R #' @param string Input vector. Either a character vector, or something #' coercible to one. #' @param pattern Pattern to look for. #' #' The default interpretation is a regular expression, as described in #' `vignette("regular-expressions")`. Use [regex()] for finer control of the #' matching behaviour. #' #' Match a fixed string (i.e. by comparing only bytes), using #' [fixed()]. This is fast, but approximate. Generally, #' for matching human text, you'll want [coll()] which #' respects character matching rules for the specified locale. #' #' Match character, word, line and sentence boundaries with #' [boundary()]. An empty pattern, "", is equivalent to #' `boundary("character")`. ``` 其他`stringr`函数可以使用`@inheritParams str_detect`来获取`string`和`pattern`的详细文档，而无需重复编写。`@inheritParams`只会继承函数实际使用且尚未文档化的参数文档，因此可以局部文档化一些参数，同时继承其他参数的文档。例如`str_match()`函数继承了`str_detect()`中`string`参数的标准文档，同时为`pattern`参数提供了自己的专业文档： ```R #' @inheritParams str_detect #' @param pattern Unlike other stringr functions, `str_match()` only supports #' regular expressions, as described `vignette("regular-expressions")`. #' The pattern should contain at least one capturing group. ``` 在编写参数文档时，有时会面临一个困境：详细描述参数信息（可接受的值、默认值、参数的使用方式等）与使文档便于在其他函数中复用（这些函数可能在某些细节上有所不同）之间存在矛盾。这就需要评估相关函数以不同方式处理相同输入是否真的值得，或者标准化是否更有益。 还可以使用标准的`::`符号从另一个包中的函数继承文档，即`@inheritParams anotherpackage::function`。但这会带来一个小问题：包的文档不再是自包含的，另一个包的版本可能会影响生成的文档。要注意贡献者使用不同版本的被继承包运行`devtools::document()`时可能引入的虚假差异。 #### 2. 函数返回值文档化 函数的输出和输入同样重要，`@returns`标签用于文档化函数的输出。其重点是描述输出的整体“形状”，即它是什么类型的对象，以及它的维度（如果适用）。 对于`stringr`包中的函数，`@returns`文档相对简单，因为几乎所有函数都返回与其中一个输入长度相同的某种类型的向量。例如，`str_like()`函数对其输出的描述如下： ```R #' @returns A logical vector the same length as `string`. ``` 更复杂的情况是`str_locate()`和`str_locate_all()`的联合文档。`str_locate()`返回一个整数矩阵，`str_locate_all()`返回一个矩阵列表，因此文档需要描述行和列的确定方式： ```R #' @returns #' * `str_locate()` returns an integer matrix with two columns and #' one row for each element of `string`. The first column, `start`, #' gives the position at the start of the match, and the second column, `end`, #' gives the position of the end. #' #'* `str_locate_all()` returns a list of integer matrices with the same #' length as `string`/`pattern`. The matrices have columns `start` and `end` #' as above, and one row for each match. #' @seealso #' [str_extract()] for a convenient way of extracting matches, #' [stringi::stri_locate()] for the underlying implementation. ``` 在其他情况下，通过考虑一组函数及其差异来确定突出的内容可能更容易。例如，大多数`dplyr`函数返回一个数据框，仅说`@returns A data frame`并不有用。相反，我们尝试确定每个函数的独特之处。我们决定从函数如何影响行、列、组和属性的角度来描述每个函数。例如，`dplyr::filter()`函数返回值的描述如下： ```R #' @returns #' An object of the same type as `.data`. The output has the following #' properties: #' #' * Rows are a subset of the input, but appear in the same order. #' * Columns are not modified. #' * The number of groups may be reduced (if `.preserve` is not `TRUE`). #' * Data frame attributes are preserved. ``` `@returns`也是描述用户可能遇到的任何重要警告或错误的好地方。例如，`readr::read_csv()`提到了如果存在解析问题会发生什么