How to include internal functions?

The functions of my R package rely on internal functions that are not of interest to the user. So far I simply don't export them, add #' @noRd, and use triple colons, (":::") whenever using them in a function that I do wish to export. CRAN check, however, creates a note:

"There are ::: calls to the package's namespace in its code. A package almost never needs to use ::: for its own objects"

Is there a better way to include internal functions so that CRAN check does not complain? Thank you for any advice.

Cheers, Christian

1 Like

You don't need to (and should not) use :: or ::: for function of you own package.

A function is not exported to user is not present in the NAMESPACE. If you use roxygen, putting @export tag ONLY for the function you want to export will do the job.

If you want no Rd file, @noRd is the way to go. However, if you want to produce a help file but not list it in the index you can use @keyword Internal. it will still be accessible using ?my_function

As a package as internaly access to its own namespace, every functions is available to use, not just the exported one. You don't use :: or ::: for function of your package. Only :: for functions exported in other package. You got the NOTE because CRAN discourage the use of an unexported function of another package.

Hope it helps

5 Likes

Excellent, thanks very much, that worked. Thank you for pointing out the @keyword internal option, which I was not aware of. This is a great way to strike a good balance between thorough documentation and a concise manual.

However, this leads to another question. All my internal functions come with an example, but these examples no longer work during CRAN check since I have added @keyword internal. I would like to maintain the examples for my internal functions. One option is to put the example code into \dontrun{}. Is this the best way to do it? Thanks very much!
Cheers, Christian

Oh I see. I am note sure what is the best practice here
But why these examples do not work anymore ? Do they use internal function ?
Because @keyword internal should have no impact on the example... :thinking:

\dontrun is clearly an option, but \donttest could be useful here. (run in examples but non in R CMD check. Maybe it is what you seek.

Thank you for your thoughts. The problem I described above occurs when not exporting the function (i.e. not using @export). If, instead, I use:

@export
@keywords internal

then everything works fine, meaning that internal functions are not documented in the PDF manual, but I can access the function from the console and CRAN check can run internal function examples, which is exactly what I wanted. Thanks again!

if you put @export in every function, it is not really Internal functions anymore I guess as it is all exported to the users. :wink:

I think that the examples are run in new sessions after the package has been loaded. So if you don't put @export the functions are not available to users, so the example can't be run because functions are inaccessible. So you need \donttest for those functions.

Your solution is perfect if it suits your need ! Glad I could help.

1 Like

OK, thanks for the clarification!
Cheers, Christian

1 Like

I once needed to use an internal function (namely tools:::fetchRdDB()) in a package. Naturally, R CMD check was quite alertive about this. I had to do such a bleak workaround:

eval(parse(text = "tools:::fetchRdDB(...)"))

This topic was automatically closed 7 days after the last reply. New replies are no longer allowed.