重复使用文档

@rdname名称

使用@rdname<目的地>¹包括多个功能。标签（例如@标题,@描述,@示例)将合并，跨越块，但这通常会产生难以理解的文本。所以我们建议您制作一个包含标题的块，描述、通用参数、示例等，然后仅在其他块中记录各个参数。

有两种基本方法可以做到这一点。您可以创建一个独立的文档块，然后向其中添加函数。这通常是当您有一系列相关的函数并且希望从其他功能（即三角（trig）在中示例如下）。

#'三角近似
#'@param x输入，弧度。
#'@name三角
无效的
#>空

#'@rdname三角
#“@导出
正弦_ish<- 功能（x） x个-x个^三 / 6

#'@rdname三角
#“@导出
cos_ish（_）<- 功能（x）1 -x个^2 / 2

#'@rdname三角
#“@导出
tan_ish（_I）<- 功能（x） x个+x个^三 / 三

或者，您可以将文档添加到现有函数中。这倾向于如果你有一个带有一些变体的“主”函数或一些助手。

#“对数
#'
#'@param x数字向量
#“@导出
日志<- 功能（x，基础）。。。

#'@rdname日志
#“@导出
日志2<- 功能（x）日志（x，2)

#'@rdname日志
#“@导出
自然对数<- 功能（x）日志（x，经验(1))

@describeIn（描述）

替代@rdname名称是@describeIn中的描述.它的语法略有不同，因为除了主题名之外还提供功能的简要描述，如@主题描述一句话描述.主要之间的差异@rdname名称和@描述输入，是那个@describeIn中的描述创建包含项目符号列出了每个函数的所有内容及其描述。它使用确定本节标题的许多启发式方法，根据您记录的相关函数、方法泛型，或类的方法。

一般来说，我不再建议@describeIn中的描述因为我不要认为它使用的启发式方法和深思熟虑的方法一样好手工制作的摘要。如果您当前正在使用@describeIn中的描述，您可以将其替换为@rdname名称，只要你考虑一下多功能@描述.

包含的顺序

默认情况下，oxygen块按其处理顺序进行处理出现在文件中。当您合并多个文件时，这可以有时会导致函数用法出现次优顺序。你可以用覆盖默认顺序@订单例如，下面的方块将放置次第一名算术。道路因为1在2之前。

#'@rdname算术
#“@订单2
添加<- 功能（x，y）x+年

#'@rdname算术
#“@订单1”
次<- 功能（x，y）x*年

参数

最古老、最常用的inherits标记是@继承参数。当多个函数对同一任务使用相同的参数名将参数记录一次，然后在其他地方继承这些文档。对于以dplyr函数为例排列（）,变（）、和总结（）它们都有一个参数已调用.数据.排列（）记录在案如此：

#'@param.data数据帧、数据帧扩展（例如tibble）或
#'惰性数据帧（例如来自dbplyr或dtplyr）。参见下面的*方法*
#'更多详细信息。
#'@param<[`data-masking`][rlang:：args_data_masking]>变量，或
#'变量的函数。使用[desc（）]按降序对变量进行排序
#'订单。
安排<- 功能（.data，…）{}

然后变（）和总结（）不需要提供@参数数据但可以继承文档来自排列（）:

#'@inheritParams排列
突变<- 功能（.data，…）{}

#'@inheritParams排列
总结<- 功能（.data，…）{}

如果这是你写的所有内容，那就不太对了，因为变（）和总结（）也会继承文档...，它具有不同的这些功能的解释。例如，变（）提供了自己的定义...:

#'@inheritParams排列
#“@param<[`data-masking`][rlang:：args_data_masking]>名称-值对。
#'名称提供输出中列的名称。
#'
#'该值可以是：
#'
#'*长度为1的向量，将循环使用到正确的长度。
#'*与当前组（或整个数据帧）长度相同的向量
#'如果未分组）。
#'*`NULL`，删除该列。
#'*数据帧或tible，用于在输出中创建多个列。
突变<- 功能（.data，…）{}

注意，只有同名参数的文档是继承的。例如，排列（）还有一个.by_group（按组）参数。由于dplyr中没有其他函数具有参数，它的文档将永远不会被继承。

多个参数

有时您会记录两个（或多个）紧密耦合的参数一起。例如，dplyr:：left_join（）有：

#'@param x，y一对数据帧、数据帧扩展（例如tibble），或
#'惰性数据帧（例如，来自dbplyr或dtplyr）。参见下面的*方法*
#'更多详细信息。

继承联合参数文档时，要么全是，要么全无，即，如果函数具有@inheritParams left_join它会的仅继承的文档x个和年如果它既有x个和年参数，两者都不是由继承函数记录。

点前缀

许多tidyverse函数接受中的命名参数...也使用.他们自己的前缀论据。这降低了争论出错的风险地点。例如，dplyr:：mutate（）有.由,.保留,.之前、和.之后参数，因为如果它们没有前缀，您将无法创建名为通过,保持,之前，或之后。我们将此模式称为点前缀.

这意味着具有相同含义的论点可以出现在两种形式：带和不带..@继承参数了解此常见模式，因此忽略.匹配参数名称时使用前缀。换句话说，.x个将继承文档x个、和x个将继承文档.x个.

继承其他组件

你可以使用@继承foo继承文档对于来自另一个主题的每个受支持的标记。目前，@继承支持继承以下标记：参数,返回,标题,描述,细节,另请参见,部分,参考文献,示例,作者,来源,笔记,格式.

通过在函数后提供以空格分隔的组件列表名称，也可以选择仅继承选定的组件。对于例子，@继承foo返回只会继承@收益标签，以及@继承foo参见source将继承@另请参见和@源标签。

@继承foo节将继承每一个 @截面标签（也可以在标记中指定使用顶级标题规范，#). 继承具体的来自另一个函数的节，使用@inheritSection foo节标题例如，所有呼噜语中的副词#'@inheritSection安全副词到继承一个标准部分，该部分提供了在中使用副词的建议程序包代码。

记录...

当函数通过时...转到另一个函数，它内联文档对于一些最常见的论据。此技术的灵感来自以下文档绘图（），其中...可以采用任何图形参数；?情节描述了一些最常见的这样您就不必查找它们?标准.

@继承DotParams有两个组件：函数inherit from和要继承的参数。因为您通常只想要记录最重要的参数，@继承DotParams附带灵活的规范受启发的论点选择dplyr:：select（）:

• @继承DotParams foo从中获取所有参数foo（）.
• @inheritDotParams foo a b e：h获取参数一,b条和之间的所有参数e（电子）和小时.
• @inheritDotParams foo-x-y采用除以下参数之外的所有参数对于x个和年.

从其他包继承

从中的其他文档主题继承是最常见的当前的包，但roxygen2也支持继承文档通过使用包：：函数语法，例如。：

• @inheritParams包：：function

• @inherit包：：function

• @inheritSection包：：function节标题

• @inheritDotParams包：：function

从另一个包继承文档时，请记住您现在对外部包有着相当强的依赖性，并且为了确保每个开发人员都生成相同的文档，您需要确保它们都安装了相同版本的软件包。如果包更改了主题或节的名称文档需要更新。由于这些原因，这种技术最好少用。