roxygenise() has side-effect of attaching the package

[slager]

roxygenise() has a side-effect of leaving the roxygenized package attached.

The documentation makes it clear that roxygenise() needs to load the package to document it, but doesn't make clear that the package will remain attached afterwards. This violated my (possibly naive) user assumption that roxygenise() would not change my attached packages, and led to some rather confusing debugging downstream (see reprex below).

See also: https://r-pkgs.org/Code.html#sec-code-r-landscape

If the behavior is necessary in the overall devtools/roxygen2 landscape, it could be helpful to update the documentation to explicitly state the side-effect.

library(usethis)
library(devtools)
library(testthat)
#> 
#> Attaching package: 'testthat'
#> The following object is masked from 'package:devtools':
#> 
#>     test_file
library(withr)

sessionInfo()
#> R version 4.3.3 (2024-02-29)
#> Platform: x86_64-pc-linux-gnu (64-bit)
#> Running under: Linux Mint 21.3
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.10.0 
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: America/Los_Angeles
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] withr_3.0.0    testthat_3.2.1 devtools_2.4.5 usethis_2.2.3 
#> 
#> loaded via a namespace (and not attached):
#>  [1] miniUI_0.1.1.1    compiler_4.3.3    brio_1.1.4        promises_1.2.1   
#>  [5] reprex_2.0.2      Rcpp_1.0.12       stringr_1.5.1     later_1.3.2      
#>  [9] yaml_2.3.8        fastmap_1.1.1     mime_0.12         R6_2.5.1         
#> [13] knitr_1.45        htmlwidgets_1.6.4 profvis_0.3.8     R.cache_0.16.0   
#> [17] shiny_1.8.0       R.utils_2.12.2    rlang_1.1.3       stringi_1.8.3    
#> [21] cachem_1.0.8      httpuv_1.6.14     xfun_0.43         fs_1.6.3         
#> [25] pkgload_1.3.4     memoise_2.0.1     cli_3.6.2         magrittr_2.0.3   
#> [29] digest_0.6.35     rstudioapi_0.16.0 xtable_1.8-4      remotes_2.4.2.1  
#> [33] lifecycle_1.0.4   R.methodsS3_1.8.2 R.oo_1.25.0       vctrs_0.6.5      
#> [37] evaluate_0.23     glue_1.7.0        urlchecker_1.0.1  styler_1.10.1    
#> [41] sessioninfo_1.2.2 pkgbuild_1.4.3    rmarkdown_2.26    purrr_1.0.2      
#> [45] tools_4.3.3       ellipsis_0.3.2    htmltools_0.5.8

is_pkg_attached <- \(pkg_name) any(grepl(pkg_name, sessionInfo()$otherPkgs))

local({
  pkg_path <- withr::local_tempdir(pattern = 'testpkg.')
  usethis::create_package(pkg_path, open = FALSE)
  pkg_name <- basename(pkg_path)
  print('is pkg attached pre-roxygenise?')
  print(is_pkg_attached(pkg_name))
  roxygen2::roxygenise(pkg_path)
  print('is pkg attached post-roxygenise?')
  print(is_pkg_attached(pkg_name))
})
#> ✔ Setting active project to '/tmp/Rtmp8rMdAN/testpkg.1138f5487a4d3'
#> ✔ Creating 'R/'
#> ✔ Writing 'DESCRIPTION'
#> Package: testpkg.1138f5487a4d3
#> Title: What the Package Does (One Line, Title Case)
#> Version: 0.0.0.9000
#> Authors@R (parsed):
#>     * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
#> Description: What the package does (one paragraph).
#> License: `use_mit_license()`, `use_gpl3_license()` or friends to pick a
#>     license
#> Encoding: UTF-8
#> Roxygen: list(markdown = TRUE)
#> RoxygenNote: 7.3.1
#> ✔ Writing 'NAMESPACE'
#> ✔ Setting active project to '<no active project>'
#> [1] "is pkg attached pre-roxygenise?"
#> [1] FALSE
#> ℹ Loading testpkg.1138f5487a4d3
#> [1] "is pkg attached post-roxygenise?"
#> [1] TRUE

print('sessionInfo() outside local')
#> [1] "sessionInfo() outside local"
# Throws error because pkg is still attached but has been deleted
sessionInfo()
#> Warning in FUN(X[[i]], ...): DESCRIPTION file of package
#> 'testpkg.1138f5487a4d3' is missing or broken
#> Error in x$Priority: $ operator is invalid for atomic vectors

^{Created on 2024-03-31 with reprex v2.0.2}

[slager]

This seems closely related to #1562.