"Failed to parse usage" warning

[dmurdoch]

I just saw a warning like r-lib/roxygen2#906 in a recent build of rgl:

> pkgdown::build_reference()
── Building function reference ─────────────────────────────────
Warning message:
Failed to parse usage: `` S3method(`persp3d`, function)(x, xlim
= c(0, 1), ylim = c(0, 1), slim = NULL, tlim = NULL, n = 101,
xvals = seq.int(min(xlim), max(xlim), length.out = n[1]), yvals
= seq.int(min(ylim), max(ylim), length.out = n[2]), svals =
seq.int(min(slim), max(slim), length.out = n[1]), tvals =
seq.int(min(tlim), max(tlim), length.out = n[2]), xlab, ylab,
zlab, col = "gray", otherargs = list(), normal = NULL,
texcoords = NULL, ...) S3method(`plot3d`, function)(x, ...) `` 

The actual code in the Rd file (hand written, not Roxygen output) was slightly different:

\method{persp3d}{function}(x, 
  xlim = c(0, 1), ylim = c(0, 1), 
  slim = NULL, tlim = NULL, 
  n = 101, 
  xvals = seq.int(min(xlim), max(xlim), length.out = n[1]), 
  yvals = seq.int(min(ylim), max(ylim), length.out = n[2]), 
  svals = seq.int(min(slim), max(slim), length.out = n[1]), 
  tvals = seq.int(min(tlim), max(tlim), length.out = n[2]), 
  xlab, ylab, zlab, 
  col = "gray", otherargs = list(), 
  normal = NULL, texcoords = NULL, \dots)
\method{plot3d}{function}(x, \ldots)

Here's my sessionInfo:

> sessionInfo()
R version 4.4.1 (2024-06-14)
Platform: aarch64-apple-darwin20
Running under: macOS Sonoma 14.6.1

Matrix products: default
BLAS:   /System/Library/Frameworks/Accelerate.framework/Versions/A/Frameworks/vecLib.framework/Versions/A/libBLAS.dylib 
LAPACK: /Library/Frameworks/R.framework/Versions/4.4-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0

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

time zone: America/Toronto
tzcode source: internal

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

other attached packages:
[1] rgl_1.3.13       testthat_3.2.1.1

loaded via a namespace (and not attached):
 [1] jsonlite_1.8.9    compiler_4.4.1    brio_1.1.5       
 [4] Rcpp_1.0.13-1     xml2_1.3.6        callr_3.7.6      
 [7] yaml_2.3.10       fastmap_1.2.0     mime_0.12        
[10] R6_2.5.1          curl_6.0.0        knitr_1.49       
[13] htmlwidgets_1.6.4 tibble_3.2.1      desc_1.4.3       
[16] rprojroot_2.0.4   pillar_1.9.0      rlang_1.1.4      
[19] utf8_1.2.4        V8_6.0.0          Rttf2pt1_1.3.12  
[22] cachem_1.1.0      xfun_0.49         fs_1.6.5         
[25] pkgload_1.4.0     memoise_2.0.1     cli_3.6.3        
[28] pkgdown_2.1.1     withr_3.0.2       magrittr_2.0.3   
[31] ps_1.8.1          digest_0.6.37     processx_3.8.4   
[34] rstudioapi_0.17.1 base64enc_0.1-3   lifecycle_1.0.4  
[37] js_1.2.1          vctrs_0.6.5       extrafont_0.19   
[40] downlit_0.4.4     evaluate_1.0.1    glue_1.8.0       
[43] extrafontdb_1.0   whisker_0.4.1     pkgbuild_1.4.5   
[46] fansi_1.0.6       rmarkdown_2.29    purrr_1.0.2      
[49] tools_4.4.1       pkgconfig_2.0.3   htmltools_0.5.8.1

If I convert the warning to an error and ask for a trace, it appears to be pkgdown:::parse_usage() that is triggering the warning.

[dmurdoch]

Just did a bisection, and this warning starts with #2385 .

Comments there suggest that my usage with no escaping of function is not allowed in \method, but I'm not seeing any R CMD check warnings or note about the syntax.

I can work around it by adding backticks on function.

[dmurdoch]

I think I saw a quote somewhere saying backticks are required, but I can't find the quote now, nor anything in the docs about this. Anyway, the workaround is fine so I'll close this.