I've just started playing around with the roxygen package and I've very happy with the results so far. However I was wondering, is there a way to specify to roxygen that it should ignore certain functions that are not user-accessible?
Specifically, I'd rather not have a .Rd file pop up because I'm using the .onLoad() hook in my package. This function is already documented in the base package so there's no reason for me to re-document it.
Well, I finally found and browsed the Roxygen-devel list at R-forge to see when this would be implemented, and it appears to already be in the version of Roxygen that is on CRAN. The key is to specify use.Rd2=TRUE when calling roxygenize(). Under this mode, Roxygen will skip creating documentation for any functions that are not preceded by Roxygen comments.
This is on their to do list - in the next version, only functions with roxygen documentation will create man files.
Use the internal keyword field (i.e. #keywords internal) to remove the function from the documentation and make it available for experienced users only.
Source: roxygen2 vignette.
Related
Long story short:
My aim is to submit a R package developed with roxygen2 to CRAN, and I need to find some guidelines on writing and documenting hidden functions.
More details:
I am writing my first R package using roxygen2 in Rstudio. I have documented all the functions I wrote so far, so that my collaborators can easily understand their purpose before going into the details of the script. All the functions that are of no use to the user, but necessary to the package, are not exported in the namespace and eliminated from the package manual/index (#keywords internal). At the same time, my collaborators can still read their documentation using the help of Rstudio.
Eventually, I would like to remove the documentation of these "hidden functions" from the help because there is no reason to keep it. I was considering to follow a suggestion I found in other posts, that is changing #' with ## in the documentation created with roxygen2. However, I am not sure this is the correct procedure to implement, and if removing the documentation of a function in the help and the manual is compatible with CRAN requirements.
Can anyone point me to some guidelines related to this issue, or has any experience to share?
I am using the devtools package to check if a package I am developing is ready for submission to CRAN.
Using Roxygen2 through devtools, I documented a small number of functions with #'#export, in order for them to be available when the package I am developing is loaded.
However, when I run devtools::check(), it seems I need to document the functions that are NOT exported, i.e. those that may be called by a function which is exported, but which are not available nor needed by whoever uses the package. Here is an example from the output of devtools::check():
checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'calculate_agreement'
‘a_assign_star’ ‘a_assign’
Do I need to document those arguments although the function is not exported?
I believe the problem here (based on past experience) is that you are probably using Roxygen comment delimiters #' in the preamble to the function. This (I'm pretty sure) triggers the creation of a .Rd file (and the need to document parameters), whether or not you have an #export directive or not. My solution in this case was to use regular # commenting rather than #'.
Based on this answer it's possible that an explicit #keywords internal directive would also work (but I haven't tried it).
I imagine this is a simple thing that I keep overlooking in the documentation, but I can't seem to figure out how to get package-level documentation to work in R. I'm not referring to function or class-specific documentation, but the documentation that you get when you type, for example, ?stats.
I've followed the general instructions I've found on the web, creating a sckeleton documentation file saved as .R. The .R file is copied with the package scripts, but the help documentation doesn't get made into a .Rd file (unless I add a function definition also named after the package).
An example of what I've tried:
#'_PACKAGE
#'MyPackage
#'
#'MyPackage description
#'
#'MyPackage details
#'#alias{MyPackage}
#'#alias{MyPackage-package}
I'm having a hard time finding good examples of how to set up general package documentation, for some reason. I've written quite a few function help files, and I know my package help file is being found by roxygen, but it's unclear why I can't generate an .Rd from it.
Answer courtesy of #slickrickulicious in the comments above:
I needed to add NULL at the end of my documentation file and include '#name MyPackage'. Doing so generated the package help file correctly.
I made my package (called pkgName) using devtools and already had a file named pkgName_package.R that was automatically generated. It contained the following lines:
#' #keywords internal
#' #aliases pkgName-package
"_PACKAGE"
After removing the first line, #keywords internal, and rebuilding, pkgName-package was a documented topic that appeared at the top of the reference manual.
I'm planning to condense some of my code into a package, and was looking at the source of a few published packages on CRAN as a guide. I notice many packages include the file R\zzz.R, so I presume there must be some convention surrounding this.
However, I cannot find any mention of zzz.R in the official Writing R Extensions guide. What is this file for, and do I need to include one in my package? Why is it named the way it is - why not zzzz.R?
It's a file where one usually puts actions on load of the package. It is tradition/convention that it's called zzz.R and could be called anything.R
You only need to include this if you want you package to do something out of the ordinary when it loads. Keep looking at what people put in there and you'll begin to get a sense of what they're used for.
This zzz.R file was also mentioned by Hadley Wickham in his book "R packages", at the bottom of "When you do need side-effects" section.
https://r-pkgs.org/Code.html#when-you-do-need-side-effects
If you use .onLoad(), consider using .onUnload() to clean up any side effects. By convention, .onLoad() and friends are usually saved in a file called R/zzz.R. (Note that .First.lib() and .Last.lib() are old versions of .onLoad() and .onUnload() and should no longer be used.)
I am writing an R package names slidify. The main function in the package is also named slidify. When I run devtools::check, I get a warning that there is a conflict in the Rd files.
I don't want to rename the function, since it succintly conveys what the package is intended for. What is best practice in this situation? Should typing ? slidify lead to the function documentation or package documentation?
Any thoughts would be appreciated.
I'd make a "slidify-package.Rd" file, (or a "slidify-package.R" file with nothing but roxygen comment blocks)
?slidify should lead to the function documentation and slidify?package should lead to the package documentation, and both help pages should have a link to the other (in the seealso section, for example)