{devtag} allows you to use @dev
tags in your roxygen2 headers so
you’ll generate help files for unexported objects, that you will enjoy
during development but won’t be accessible for users that install your
package.
This is done by adding the relevant help files to “.Rbuildignore” when
documenting the package with {roxygen2} (usually through
devtools::document()
)
These files are not git ignored so they are version-controlled and shared with contributors of your repo.
Install with
remotes::install_github("moodymudskipper/devtag")
To use {devtag} :
-
Use “@dev” for unexported functions where you would have used “@export” for exported functions.
-
Have in your DESCRIPTION file the line :
Roxygen: list(markdown = TRUE, roclets = c("collate", "rd", "namespace", "devtag::dev_roclet"))
This will make sure that when you call document()
{devtag} will be
triggered.
- Have in your
yourpkg.Rproj
file the line:
PackageRoxygenize: rd,collate,namespace,devtag::dev_roclet
This will make sure than Ctrl+Shift+D, or documenting through the UI in
RStudio, triggers {devtag}. You can call file.edit("yourpkg.Rproj")
since clicking on the file might open the project rather than open the
file for editing.
- That’s it! Note that to check that it works you’ll need to use
devtools::install()
, clicking the Install button in the build pane will still install the build ignored help files with the package (not really a bad thing on your machine anyway).
We set up the package {devtag.example} as an example. You can check the code at https://github.com/moodymudskipper/devtag.example
If you install it you won’t be able to see the help file for the
subtract()
function, but if you clone it and use a {devtools} workflow
you will had access to it.
@noRd
doesn’t produce help files, it basically makes your roxygen2 blocks regular comments that look like regular documentation@keywords internal
removes help files from the index but they are still accessible by users