roxygen2 7.3.0

  2024/01/11

  roxygen2

  Hadley Wickham

We’re well pleased to announce the release of roxygen2 7.3.0. roxygen2 allows you to write specially formatted R comments that generate R documentation files (man/*.Rd) and the NAMESPACE file. roxygen2 is used by over 13,000 CRAN packages.

You can install it from CRAN with:

install.packages("roxygen2")

There are four major improvements in this release:

  • The NAMESPACE roclet now reports if you have S3 methods that are missing an @export tag. All S3 methods need to be @exported even if the generic is not. This avoids rare, but hard to debug, problems. If you think this is giving a false positive, please file an issue and suppress the warning with @exportS3Method NULL.

    I’ve also considerably revamped the documentation for S3 methods in vignette("namespace"). The docs now discuss what exporting an S3 method really means, and why it would be technically better to call it registering the method.

  • Finally, the NAMESPACE roclet once again regenerates imports before loading package code and parsing roxygen blocks. This has been the goal for a long time, but we accidentally broke it when adding support for code execution in markdown blocks. This change resolves a family of problems where you somehow bork your NAMESPACE and can’t easily get fix it because you can’t re-document the package because you can’t load your package because your NAMESPACE is borked.

  • @docType package now works like "_PACKAGE", including creating a {packagename}-package alias automatically. This resolves a bug introduced in roxygen2 7.0.0 that meant that many packages lacked the correct alias for their package documentation topic.

  • "_PACKAGE" does a better job of automatically generating aliases. In particular, it will no longer generate a duplicate alias if you have a function with the same name as your package (like glue::glue() or reprex::reprex()). If you’ve previously had to hack around this bug, you can now delete any custom @aliases tags associated with the "_PACKAGE" docs.

You can see a full list of other minor improvements and bug fixes in the release notes.

Acknowledgements

A big thanks to the 46 folks who helped make this release possible through their thoughtful questions and carefully crafted code! @andrewmarx, @ashbythorpe, @ateucher, @bahadzie, @bastistician, @beginb, @brodieG, @bryanhanson, @cbielow, @daattali, @DanChaltiel, @dpprdan, @dsweber2, @espinielli, @hadley, @hughjonesd, @jeroen, @jmbarbone, @johnbaums, @jonocarroll, @kathi-munk, @krlmlr, @kylebutts, @lionel-, @LouisLeNezet, @maelle, @MaximilianPi, @MichaelChirico, @moodymudskipper, @msberends, @multimeric, @musvaage, @neshvig10, @olivroy, @ralmond, @RMHogervorst, @Robinlovelace, @rossellhayes, @rsbivand, @sbgraves237, @schradj, @sebffischer, @simonpcouch, @stemangiola, @tau31, and @trusch139.

Contents