roxygen2: @noRd tag has no effect in presence of the @rdname tag in documenting internal functions

Viewed 657

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 prevent Rd files 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:

  1. Comment out the internal functions or
  2. have one internal function per file to avoid using @rdname tag.

However, these solutions violate the spirit of roxygen2.

1 Answers

Please roxygen2 github page for the answer to this question. Thanks, @gaborcsardi.

https://github.com/r-lib/roxygen2/issues/1141#issuecomment-660612297 (copied from there):

Roxygen blocks and roxygen tags apply to the expression after them, so you'll need to put the @noRd in front of the expression you don't want the .Rd file for. Maybe you'll also have to remove @rdname, I don't know, but it us useless with @noRd, anyway:

#' @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
#' @noRd

ilovecats <- function(loveCats){
  if(loveCats){
    print("you love cats")
  } else{
      print("you hate cats")
    }
}

See this for an alternative that only leaves the internal function out of the index: https://blog.r-hub.io/2019/12/12/internal-functions/#how-to-document-internal-functions

Related