Exclude function from R package manual

17
votes

I'm writing an R package, and I'm documenting all of my functions with roxygen2. However, I do not want all functions to appear in the manual of the package. How can I specify which functions should appear in the package manual, or which ones should not?

I am aware that naming a function with a leading dot, e.g. .f <- function() instead of f <- function() is a solution. Are there other solutions?

1
rdocumentationpackageroxygen2
Why document them if you don't want them in the manual? - nrussell
Because it is useful both for me when recalling what functions do, and for others who might want to use the "hidden" functions. I believe I have seen examples in other packages where I could not find the help page of the function by writing ?function_name in the console after importing the package, but I was able to see the help page if I wrote ?pkgname:::function_name. I could be remembering wrong though. - Benjamin Allévius
But functions accessed with ::: are not exported from packages - which typically means the author did not intend for clients to use the function. Generally such functions are not documented - e.g. tools:::.is_ASCII. I would guess that if you encountered a non-exported function that does have documentation, most likely it was previously an exported (and documented) function, and removed from the list of exports in a later version. - nrussell
exported or nonexported functions will have a man/ document created via roxygen2 if you use the package as designed. The way that I do what you're describing is to not include the quote in the comment so roxygen doesn't pick it up. eg want help file: #' @param ... don't want help file # @param ... Here's an example - Alex W

1 Answers

29
votes

I had missed the following detail in the excellent book R packages by Hadley Wickham (in the section on object documentation):

@keywords keyword1 keyword2 ... adds standardised keywords. Keywords are optional, but if present, must be taken from a predefined list found in file.path(R.home("doc"), "KEYWORDS").

Generally, keywords are not that useful except for @keywords internal. Using the internal keyword removes the function from the package index and disables some of their automated tests. It’s common to use @keywords internal for functions that are of interest to other developers extending your package, but not most users.

So adding @keywords internal to the roxygen2 function documentation results in the function not appearing in the package manual/index, while still making the help page be accessible after loading the package.