Bug: Roxygen2 ignores @export when Rcpp::depends() or Rcpp::plugins() are present

[gregorgorjanc]

I spotted a bug when working on tskitr package (that exposes tskit C API via Rcpp) and it's downstream use in AlphaSimR. When I specify [[Rcpp::depends()]] or [[Rcpp::plugins()]] (in addition to [[Rcpp:export]]) it seems that roxygen2 does not export documentation from C++ file (even though I am specifying //' @export.

To reproduce this bug do the following:

# 1) Install tskitr
remotes::install_github(repo = "HighlanderLab/tskitr/R")

# 2) Checkout AlphaSimR commit that exposed the bug
git clone https://github.com/HighlanderLab/AlphaSimR.git
cd AlphaSimR
git checkout ts
git checkout 12657b08e7054d88bc214413d13f36c7cde60d95

# 3) Explore the C++ file exposing the issue
cat src/ts.cpp

giving

#include "alphasimr.h"
...
//' @title Get number of individuals in tree sequence
//' @description Get number of individuals in tree sequence
//' @param ts an external pointer to a \code{tsk_treeseq_t} object.
//' @return integer number of individuals
//' @examples
//' ts_file <- system.file("examples", "test.trees", package = "tskitr")
//' ts <- tskitr::ts_load(ts_file) # slendr also has ts_load()!
//' tskitr::ts_num_individuals(ts)
//' ts_num_individuals(ts)
//' ts_num_individuals2(ts)
//' AlphaSimR::ts_num_individuals2(ts)
//' AlphaSimR:::ts_num_individuals2(ts)
//'
//' @export
// [[Rcpp::depends(tskitr)]]
// [[Rcpp::plugins(tskitr)]]
// [[Rcpp::export]]
int ts_num_individuals2(SEXP ts) {
   int n;
   Rcpp::XPtr<tsk_treeseq_t> xptr(ts);
   n = (int) tsk_treeseq_get_num_individuals(xptr);
   return n;
}

# 4) Start R
R

# 5) Roxygenise the package
devtools::document()

# 6) Check if @export was honoured
grep ts_num_individuals2 NAMESPACE # giving zero hits
ls man | grep ts_num_individuals2 # giving zero hits
cat R/RcppExports.R # at the end of the file you will see undocumented ts_num_individuals2() function

7. When I remove these two lines:

// [[Rcpp::depends(tskitr)]]
// [[Rcpp::plugins(tskitr)]]

the compilation fails (because I need the depends and plugins), but changing the function to the following enables compilation and repeat of steps 4-6, showing that the function is exported and documented.

#include "alphasimr.h"
//' @title Get number of individuals in tree sequence
//' @description Get number of individuals in tree sequence
//' @param ts an external pointer to a \code{tsk_treeseq_t} object.
//' @return integer number of individuals
//' @examples
//' ts_num_individuals2()
//' AlphaSimR::ts_num_individuals2()
//' AlphaSimR:::ts_num_individuals2()
//'
//' @export
// [[Rcpp::export]]
int ts_num_individuals2(SEXP ts) {
   int n;
   n = 0;
   return n;
}

Here are details of my setup:

> R.version
               _
platform       aarch64-apple-darwin20
arch           aarch64
os             darwin20
system         aarch64, darwin20
status
major          4
minor          5.0
year           2025
month          04
day            11
svn rev        88135
language       R
version.string R version 4.5.0 (2025-04-11)
nickname       How About a Twenty-Six

> sessionInfo()
R version 4.5.0 (2025-04-11)
Platform: aarch64-apple-darwin20
Running under: macOS Sequoia 15.7.3

Matrix products: default
BLAS:   /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRblas.0.dylib
LAPACK: /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1

locale:
[1] en_GB.UTF-8/en_GB.UTF-8/en_GB.UTF-8/C/en_GB.UTF-8/en_GB.UTF-8

time zone: Europe/Ljubljana
tzcode source: internal

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

loaded via a namespace (and not attached):
[1] compiler_4.5.0

> packageDescription("roxygen2")
Package: roxygen2
Title: In-Line Documentation for R
Version: 7.3.3
Authors@R: c( person("Hadley", "Wickham", , "hadley@posit.co", role =
        c("aut", "cre", "cph"), comment = c(ORCID =
        "0000-0003-4757-117X")), person("Peter", "Danenberg", ,
        "pcd@roxygen.org", role = c("aut", "cph")), person("Gábor",
        "Csárdi", , "csardi.gabor@gmail.com", role = "aut"),
        person("Manuel", "Eugster", role = c("aut", "cph")),
        person("Posit Software, PBC", role = c("cph", "fnd"), comment =
        c(ROR = "03wc8by49")) )
Description: Generate your Rd documentation, 'NAMESPACE' file, and
        collation field using specially formatted comments. Writing
        documentation in-line with code makes it easier to keep your
        documentation up-to-date as your requirements change.
        'roxygen2' is inspired by the 'Doxygen' system for C++.
License: MIT + file LICENSE
URL: https://roxygen2.r-lib.org/, https://github.com/r-lib/roxygen2
BugReports: https://github.com/r-lib/roxygen2/issues
Depends: R (>= 3.6)
Imports: brew, cli (>= 3.3.0), commonmark, desc (>= 1.2.0), knitr,
        methods, pkgload (>= 1.0.2), purrr (>= 1.0.0), R6 (>= 2.1.2),
        rlang (>= 1.0.6), stringi, stringr (>= 1.0.0), utils, withr,
        xml2
Suggests: covr, R.methodsS3, R.oo, rmarkdown (>= 2.16), testthat (>=
        3.1.2), yaml
LinkingTo: cpp11
VignetteBuilder: knitr
Config/Needs/development: testthat
Config/Needs/website: tidyverse/tidytemplate
Config/testthat/edition: 3
Config/testthat/parallel: TRUE
Encoding: UTF-8
Language: en-GB
RoxygenNote: 7.3.2.9000
NeedsCompilation: yes
Packaged: 2025-09-03 20:12:40 UTC; hadleywickham
Author: Hadley Wickham [aut, cre, cph] (ORCID:
        <https://orcid.org/0000-0003-4757-117X>), Peter Danenberg [aut,
        cph], Gábor Csárdi [aut], Manuel Eugster [aut, cph], Posit
        Software, PBC [cph, fnd] (ROR: <https://ror.org/03wc8by49>)
Maintainer: Hadley Wickham <hadley@posit.co>
Repository: CRAN
Date/Publication: 2025-09-03 21:40:02 UTC
Built: R 4.5.0; aarch64-apple-darwin20; 2025-09-03 22:17:19 UTC; unix
Archs: roxygen2.so.dSYM
RemoteType: standard
RemotePkgRef: roxygen2
RemoteRef: roxygen2
RemoteRepos: https://cloud.r-project.org
RemoteSha: 7.3.3

-- File: /Users/ggorjanc/Library/R/arm64/4.5/library/roxygen2/Meta/package.rds

Happy to provide more information! I don't know though where I could start looking for the source of this bug.

Thanks!

[gregorgorjanc]

This issue/bug goes away when I move the depends and plugin attrributes to the top of the file. I personally find this as an even better solution - assuming that all functions in the whole file will be affected by this call. I will leave the issue open to let the authors decide if this is a bug or a feature - I am OK if this issue is closed (I have a workaround).

#include "alphasimr.h"
// [[Rcpp::depends(tskitr)]]
// [[Rcpp::plugins(tskitr)]]

//' @title Get number of individuals in tree sequence
//' @description Get number of individuals in tree sequence
//' @param ts an external pointer to a \code{tsk_treeseq_t} object.
//' @return integer number of individuals
//' @examples
//' ts_file <- system.file("examples", "test.trees", package = "tskitr")
//' ts <- tskitr::ts_load(ts_file) # slendr also has ts_load()!
//' tskitr::ts_num_individuals(ts)
//' ts_num_individuals(ts)
//' ts_num_individuals2(ts)
//' AlphaSimR::ts_num_individuals2(ts)
//' AlphaSimR:::ts_num_individuals2(ts)
//'
//' @export
// [[Rcpp::export]]
int ts_num_individuals2(SEXP ts) {
   int n;
   Rcpp::XPtr<tsk_treeseq_t> xptr(ts);
   n = (int) tsk_treeseq_get_num_individuals(xptr);
   return n;
}