I am using roxygen2 package to document my package. As suggested by Hadley Wickham in section 7.8,
Internal functions should be documented with
#'comments as per usual. Use the @noRd tag to preventRdfiles from being generated.
Often, I have internal functions in one R file and thus use the @rdname tag. Yet if I use the @noRd tag it has no effect.
For instance, if you roxygenize() this file called "iloveAnimals", inside a package:
#' @title Cats
#' @name iloveAnimals
#'
#' @description The following logical functions check if you love animals
#'
#' @param loveCats Logical; TRUE if you love Cats
#' @details
#' loveCats: do you love cats
#' @rdname iloveAnimals
ilovecats <- function(loveCats){
if(loveCats){
print("you love cats")
} else{
print("you hate cats")
}
}
#' @param loveBirds logical; TRUE if you love birds.
#' @details
#' loveBirds: Do you love birds?
#' @rdname iloveAnimals
ilovebirds <- function(loveBirds){
if(loveBirds){
print("you love birds")
} else{
print("you hate birds")
}
}
#' @noRd
yields, within a package,
roxygen2::roxygenize()
Writing NAMESPACE
Writing NAMESPACE
Writing iloveAnimals.Rd
This is surprising as the Rd file should not be written. The Rd file is written as if the @noRd tag has no effect. If @rdname is not used, the @noRd tag works and the Rd file is not written. There are two easy solutions:
- Comment out the internal functions or
- have one internal function per file to avoid using @rdname tag.
However, these solutions violate the spirit of roxygen2.