Automate #usage documentation in Rcpp functions - r

Question

How can I automate the documentation of the #usage section for Rcpp functions? In an ordinary R function within a package documented using roxygen2, the Usage section is added automatically. This is convenient for automatically documenting default arguments.
#' #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'
Yet when I write an analogous script with Rcpp, the documentation is produced but no #usage section is written.
//' 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.
I looked at the source code and documentation for dplyr::between, but there doesn't seem to be any special #usage section, yet the #usage section is present in the documentation.
I also looked at http://r-pkgs.had.co.nz/man.html and http://dirk.eddelbuettel.com/code/rcpp/Rcpp-attributes.pdf and Ctrl-F'd for usage, but found nothing relevant.
I know I can add //' #usage rcpp_hello(CharVec = TRUE) in this particular case but the advantage of letting roxygen2 automate the process is that I can change the default arguments.
DESCRIPTION file:
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 info:
> 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

You haven't needed to use #usage since Roxygen2 2.0 and 3.0.0 for R or Rcpp. The issue you are running into is your roxygen tags are not directly above the Rcpp attributes tag...
#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;
}
Try the above. This also means you do not need the #name tag either...