Automate @usage documentation in Rcpp functions

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...