Request: make missing link warnings more verbose

[mjsteinbaugh]

Hi, I'm seeing this warning now pop up in roxygen2 for one of my packages:

Warning: Link to unknown topic in inherited text: methods::StructureClasses

I'm having trouble locating the source of this warning. Is there a way we can tweak roxygen2 to return which Rd file and line in particular is causing the issue?

[mjsteinbaugh]

Is pull #1109 potentially related?

[gaborcsardi]

Is there a way we can tweak roxygen2 to return which Rd file and line in particular is causing the issue?

Maybe, but you can also search for StructureClasses in your Rd files for now?

[mjsteinbaugh]

Hi @gaborcsardi , just figured it out.

I was using this line to inherit some params from as_tibble documentation:

#' @inheritParams tibble::as_tibble

Taking this out gets rid of the warning. I think it may have to do with this Rd code being linked:

\item{rownames}{How to treat existing row names of a data frame or matrix:
\itemize{
\item \code{NULL}: remove row names. This is the default.
\item \code{NA}: keep row names.
\item A string: the name of a new column. Existing rownames are transferred
into this column and the \code{row.names} attribute is deleted.
Read more in \link[tibble]{rownames}.
}}

Not sure how that goes up the stack to result in the StructureClasses warning.

See related commit in pipette package for details.

[gaborcsardi]

Interesting. I'll reopen this, because it seems to be a bug if StructureClasses is not used in the Rd at all.

[mjsteinbaugh]

I'm hitting this issue again with another package, and the warning is time consuming to debug. This time I'm hitting:

Warning: Link to unknown topic in inherited text: stats::bandwidth

And I have no idea which Rd file this link is being pulled from. If there is a way to add a traceback for the link failure, it would be super helpful.

[mjsteinbaugh]

In case anyone else hits an issue like this, here's the link problem I hit:

https://github.com/acidgenomics/pointillism/blob/v0.4.12/R/plotCounts-methods.R#L11

#' @inheritParams ggplot2::geom_violin

[dmurdoch]

This seems related: I want to add a Note to the pkgbuild::build documentation containing a link to devtools::submit_cran.

But devtools::build has @inherit pkgbuild::build, so processing devtools triggers a series of warnings Warning: Link to unknown topic in inherited text: devtools::submit_cran. This happens even though the Note would not be inherited, according to the docs at

roxygen2/vignettes/rd.Rmd

Line 436 in 513c9e2

* `@inherit source_function` will inherit parameters, return, references,

[baderstine]

@mjsteinbaugh this is newly happening in one of my packages. How did you find the source of it?

[mjsteinbaugh]

@baderstine It's a tough thing to track down. I've been looking through the Rd documentation files manually until I spot the problem.

[phargarten2]

@mjsteinbaugh I recently updated all dependent packages and updated the R version to the latest version, v. 4.0.5. Using devtools::document(), the warning mentioned above is now coming up in the new version of roxygen2 (7.1.1) that it didn't before.

Warning: Link to unknown topic in inherited text: tools::print.via.format

print.via.format() did not show up in any Rd file.

Session Info: ``` R version 4.0.5 (2021-03-31) Platform: x86_64-apple-darwin17.0 (64-bit) Running under: macOS Big Sur 10.16, RStudio 1.2.1335

Locale: en_US.UTF-8 / en_US.UTF-8 / en_US.UTF-8 / C / en_US.UTF-8 / en_US.UTF-8

Package version:
askpass_1.1 assertthat_0.2.1 backports_1.2.1 base64enc_0.1-3
BH_1.75.0.0 brew_1.0.6 brio_1.1.1 cachem_1.0.4
callr_3.6.0 checkmate_2.0.0 cli_2.3.1 clipr_0.7.1
cluster_2.1.1 coda_0.19-4 colorspace_2.0-0 commonmark_1.7
compiler_4.0.5 condMVNorm_2020.1 conquer_1.0.2 covr_3.5.1
cpp11_0.2.7 crayon_1.4.1 credentials_1.3.0 crosstalk_1.1.1
curl_4.3 data.table_1.14.0 desc_1.3.0 devtools_2.3.2
diffobj_0.3.4 digest_0.6.27 dplyr_1.0.5 DT_0.17
ellipsis_0.3.1 evaluate_0.14 fansi_0.4.2 farver_2.1.0
fastmap_1.1.0 foreign_0.8-81 Formula_1.2-4 fs_1.5.0
generics_0.1.0 gert_1.3.0 ggplot2_3.3.3 gh_1.2.1
gitcreds_0.1.1 glm2_1.2.1 glue_1.4.2 gmm_1.6-6
graphics_4.0.5 grDevices_4.0.5 grid_4.0.5 gridExtra_2.3
gtable_0.3.0 highr_0.8 Hmisc_4.5-0 htmlTable_2.1.0
htmltools_0.5.1.1 htmlwidgets_1.5.3 httr_1.4.2 ini_0.3.1
invgamma_1.1 isoband_0.2.4 jpeg_0.1-8.1 jsonlite_1.7.2
knitr_1.31 labeling_0.4.2 later_1.1.0.1 lattice_0.20-41
latticeExtra_0.6-29 lazyeval_0.2.2 lifecycle_1.0.0 magrittr_2.0.1
markdown_1.1 MASS_7.3-53.1 Matrix_1.3-2 MatrixModels_0.5-0
matrixNormal_0.0.4 matrixStats_0.58.0 mcmc_0.9-7 MCMCpack_1.5-0
memoise_2.0.0 methods_4.0.5 mgcv_1.8.34 mime_0.10
miWQS_0.4.5 munsell_0.5.0 mvtnorm_1.1-1 nlme_3.1.152
nnet_7.3-15 openssl_1.4.3 parallel_4.0.5 pillar_1.5.1
pkgbuild_1.2.0 pkgconfig_2.0.3 pkgload_1.2.0 png_0.1-7
praise_1.0.0 prettyunits_1.1.1 processx_3.5.0 promises_1.2.0.1
ps_1.6.0 purrr_0.3.4 quantreg_5.85 R6_2.5.0
rappdirs_0.3.3 rcmdcheck_1.3.3 RColorBrewer_1.1-2 Rcpp_1.0.6
RcppArmadillo_0.10.2.2.0 rematch2_2.1.2 remotes_2.3.0 rex_1.2.0
rlang_0.4.10 rlist_0.4.6.1 roxygen2_7.1.1 rpart_4.1-15
rprojroot_2.0.2 Rsolnp_1.16 rstudioapi_0.13 rversions_2.0.2
sandwich_3.0-0 scales_1.1.1 sessioninfo_1.1.1 SparseM_1.81
splines_4.0.5 stats_4.0.5 stats4_4.0.5 stringi_1.5.3
stringr_1.4.0.9000 survival_3.2-10 sys_3.4 testthat_3.0.2
tibble_3.1.0 tidyr_1.1.3 tidyselect_1.1.0 tmvmixnorm_1.1.1
tmvtnorm_1.4-10 tools_4.0.5 truncnorm_1.0-8 usethis_2.0.1
utf8_1.2.1 utils_4.0.5 vctrs_0.3.7 viridis_0.5.1
viridisLite_0.3.0 waldo_0.2.5 whisker_0.4 withr_2.4.1
xfun_0.22 XML_3.99.0.6 xml2_1.3.2 xopen_1.0.0
yaml_2.2.1 zip_2.1.1 zoo_1.8-9

</details>

[ColinFay]

I'm getting the same as @phargarten2.

> devtools::document()
ℹ Updating golem documentation
ℹ Loading golem
Writing NAMESPACE
Warning: Link to unknown topic in inherited text: tools::print.via.format
Writing NAMESPACE
>
> sessionInfo()
R version 4.0.5 (2021-03-31)
Platform: x86_64-apple-darwin17.0 (64-bit)
Running under: macOS High Sierra 10.13.6

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.0/Resources/lib/libRlapack.dylib

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

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

other attached packages:
[1] golem_0.3.1

loaded via a namespace (and not attached):
 [1] xfun_0.22         remotes_2.3.0     purrr_0.3.4       rcmdcheck_1.3.3   vctrs_0.3.7      
 [6] testthat_3.0.2    usethis_2.0.1     htmltools_0.5.1.1 yaml_2.2.1        utf8_1.2.1       
[11] rlang_0.4.10      pkgbuild_1.2.0    later_1.1.0.1     pillar_1.5.1      glue_1.4.2       
[16] withr_2.4.1       xopen_1.0.0       sessioninfo_1.1.1 lifecycle_1.0.0   stringr_1.4.0    
[21] commonmark_1.7    devtools_2.4.0    memoise_2.0.0     knitr_1.31        callr_3.6.0      
[26] fastmap_1.1.0     httpuv_1.5.5      ps_1.6.0          fansi_0.4.2       Rcpp_1.0.6       
[31] xtable_1.8-4      promises_1.2.0.1  cachem_1.0.4      desc_1.3.0        pkgload_1.2.1    
[36] jsonlite_1.7.2    debugme_1.1.0     config_0.3.1      mime_0.10         fs_1.5.0         
[41] digest_0.6.27     stringi_1.5.3     processx_3.5.1    shiny_1.6.0       rprojroot_2.0.2  
[46] here_1.0.1        cli_2.4.0         tools_4.0.5       magrittr_2.0.1    dockerfiler_0.1.3
[51] tibble_3.1.0      crayon_1.4.1      pkgconfig_2.0.3   ellipsis_0.3.1    xml2_1.3.2       
[56] prettyunits_1.1.1 attempt_0.3.1     roxygen2_7.1.1    rstudioapi_0.13   R6_2.5.0         
[61] compiler_4.0.5 

[jatkins23]

I have the same error but the source is @inheritDotParams dplyr::as_tibble and the missing topic is magrittr::pipe which seems pretty clearly documented and included in my package. @mjsteinbaugh, not sure I understood your follow up but were you able to remove this error?

[mjsteinbaugh]

@jatkins23 Still an unresolved issue, unfortunately! What I started doing in my code is intentionally avoid linking to package documentation that I don't write myself. This helps avoid breaking changes that are then hard to debug currently with roxygen2.

[hadley]

Does anyone have a reprex for this?

[mjsteinbaugh]

@hadley I'll see if I can make one this week

[hadley]

Note to self: looks like there are at least two problems here:

• Start by moving tweak_links() into rd-inherits.R

• All the warnings in rd-inherit.R need to provide additional info about the source of the warning. It looks like the information about the tag is lost by this point (although it's worth checking to see if it can be preserved) but we can still include the topic name in the warning.

• Looks like the links are tweaked too aggressively — we're tweaking the entire Rd file, not just the bit that's inherited. Can probably just do the tweaking in inherit_field.

[ColinFay]

Hey,

So, this is not a perfect reprex as it is not minimal but here is a way to reliably reproduce this:

docker run -it rocker/tidyverse:4.0.5 bash
git clone -b v0.3.2 https://github.com/ThinkR-open/golem
cd golem
Rscript -e "remotes::install_deps();devtools::document()"

which will end up with :

ℹ Loading golem
Writing NAMESPACE
Warning: Link to unknown topic in inherited text: tools::print.via.format
Warning: Link to unavailable package in inherited text: spelling::spell_check_package. there is no package called ‘spelling’
Warning: Link to unavailable package in inherited text: spelling::wordlist. there is no package called ‘spelling’
Writing NAMESPACE

[hadley]

@ColinFay thanks!

[hadley]

I should have a fix for this later today or tomorrow, but my analysis suggests that these warnings are almost always harmless and you can just ignore them.