CRAN compatible method of documenting internal functions


Say I have an internal (non-exported function) which is documented with examples. A build check will correctly throw errors since has_class isn't exported.

Normally I'd just use ::: but to access internal functions, but i've had packages rejected from cran for these reasons.

I've seen other threads mention @noRd, which seems to be the best solution - but I find it more convenient for package maintenance to have the full roxygen documentation present (you lose features like paramater inheritance with @noRd)

Is there a a solution thats OK for CRAN but lets me document internal functions similarly to exported functions?

#' Check object is some class
#' This function checks whether object is a specific class
#' @param x A value to check.
#' @param class checks if `x` belongs to `class`. If multiple values of `class` are supplied, returns whether `x` belongs to any of them (character)
#' @return A logical scalar indicating `x` belongs to `class`
#' has_class(1, "numeric") # TRUE
#' has_class(1, "character") # FALSE
has_class <- function(x, class){
  return(inherits(x, what = class))

I don't think that should happen. Can you show us your package?

This blog post could be also useful: Internal functions in R packages - R-hub blog

Sounds related to this closed (so unimplemented) devtools feature request: Could `@noRd` create build ignored help files for developers ? · Issue #2400 · r-lib/devtools · GitHub

I think there is a way.
We can .Rbuildignore the help files we don't want on cran (the .Rd files under man/).
So for instance you'd have a line in your ".Rbuildignore" file with "^man/my_topic.Rd$".

When installing from the GUI for some reason the build ignored files under man/ are still integrated into the package and I first thought it was an R issue, but in fact when using devtools::install()from the console it works well and the help file is not integrated in the package. devtools::build() works fine as well from the console and we can verify in the tar.gz that the files are not there.

I would assume, but I'm not sure about it, that devtools::release() would use devtools::install() the proper way so maybe we can use the devtools workflow and not worry about the weird behavior of the UI.

We might define a custom roxygen tag to add relevant topics to .Rbuildignore automatically

1 Like

@selkamand I've build a package around this idea, this might help: GitHub - moodymudskipper/devtag: Restrict Help Files to Development

1 Like

This topic was automatically closed after 45 days. New replies are no longer allowed.

If you have a query related to it or one of the replies, start a new topic and refer back with a link.