在 Rcpp 函数中自动化 @usage 文档

Question

我如何自动化 Rcpp 函数的 @usage 部分的文档？ 在使用 [=16 记录的包中的普通 R 函数中=], 用法部分会自动添加。这对于自动记录默认参数很方便。

#' @title Hello world
#' @return Prints 'Hello world'
#' @export
#' @useDynLib RcppSandBox

hello <- function(x = 1) {
  print("Hello, world!")
}

Hello world

Usage

hello(x = 1)

Value

Prints 'Hello world'

然而，当我使用 Rcpp 编写类似的脚本时，生成了文档但没有写入 @usage 部分。

//' Hello, Rcpp!
//' @name rcpp_hello
//' @param CharVec Print x or not.
//' @export

#include <Rcpp.h>
using namespace Rcpp;

// This is a simple function using Rcpp that creates an R list
// containing a character vector and a numeric vector.
//
// Learn more about how to use Rcpp at:
//
//   http://www.rcpp.org/
//   http://adv-r.had.co.nz/Rcpp.html
//
// and browse examples of code using Rcpp at:
//
//   http://gallery.rcpp.org/
//

// [[Rcpp::export]]
List rcpp_hello(bool CharVec = true) {
  CharacterVector x = CharacterVector::create("foo", "bar");
  NumericVector y   = NumericVector::create(0.0, 1.0);
  List z            = List::create(x, y);
  if (CharVec) {
  } else {
    List z = List::create(y);
  }
  return z;
}

Hello, Rcpp!

Description

Hello, Rcpp!

Arguments

CharVec Print x or not.

我查看了 dplyr::between 的源代码和文档，但似乎没有任何特殊的 @usage 部分，但 @usage 部分存在于文档中.

我也查看了 http://r-pkgs.had.co.nz/man.html and http://dirk.eddelbuettel.com/code/rcpp/Rcpp-attributes.pdf 和 Ctrl-F 的用法，但没有发现任何相关内容。

我知道我可以在这种特殊情况下添加 //' @usage rcpp_hello(CharVec = TRUE)，但让 roxygen2 自动化该过程的好处是我可以更改默认参数。

描述文件：

Package: RcppSandBox
Type: Package
Title: What the Package Does (Title Case)
Version: 0.1.0
Author: Who wrote it
Maintainer: The package maintainer <yourself@somewhere.net>
Description: More about what it does (maybe more than one line)
    Use four spaces when indenting paragraphs within the Description.
License: What license is it under?
Encoding: UTF-8
LazyData: true
Imports: Rcpp (>= 0.12.10)
LinkingTo: Rcpp
RoxygenNote: 6.0.1

Session 信息：

> sessionInfo()
R version 3.4.0 (2017-04-21)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows >= 8 x64 (build 9200)

Matrix products: default

locale:
[1] LC_COLLATE=English_Australia.1252  LC_CTYPE=English_Australia.1252    LC_MONETARY=English_Australia.1252
[4] LC_NUMERIC=C                       LC_TIME=English_Australia.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] RcppSandBox_0.1.0    dplyr_0.5.0          RevoUtilsMath_10.0.0

loaded via a namespace (and not attached):
[1] compiler_3.4.0   magrittr_1.5     R6_2.2.2         assertthat_0.2.0 RevoUtils_10.0.4 DBI_0.6-1        tools_3.4.0     
[8] tibble_1.3.0     Rcpp_0.12.10

Answer 1

自 Roxygen2 2.0 和 3.0.0 以来，您不需要为 R 或 Rcpp 使用 @usage。您运行遇到的问题是您的 roxygen 标签不在 Rcpp 属性标签的正上方...

#include <Rcpp.h>

//' Hello, Rcpp!
//' @param CharVec Print x or not.
//' @export
// [[Rcpp::export]]
Rcpp::List rcpp_hello(bool CharVec = true) {
  Rcpp::CharacterVector x = Rcpp::CharacterVector::create("foo", "bar");
  Rcpp::NumericVector y   = Rcpp::NumericVector::create(0.0, 1.0);
  Rcpp::List z            = Rcpp::List::create(x, y);
  if (CharVec) {
  } else {
    Rcpp::List z = Rcpp::List::create(y);
  }
  return z;
}

试试上面的方法。这也意味着您也不需要 @name 标签...

在 Rcpp 函数中自动化 @usage 文档

Automate @usage documentation in Rcpp functions

r

rcpp

roxygen2

Hello world

Hello, Rcpp!

描述文件：

Session 信息：