Roxygen2: Using @inheritParams to inherit from a @noRd block

[nlneas1]

@hadley and @kevinushey I have read through #641, as well as the subsequent issue and PR. However it would appear that it is not possible to use @inheritParams to inherit parameters from a function documented with the @noRd tag. I have tested this and it doesn't work in versions 6.1.1 and 7.1.1 unless I am misunderstanding. Let's say we have the following.

#' Function A
#' @param A `character` string, `NULL` by default.
#' @noRd
functionA <- function(a = NULL) {
  print(a)
}

#' Function B
#' @inheritParams functionA
#' @export
functionB <- function(a = NULL) {
  functionA(a = a)
}

This will just give me

Can't find help topic 'functionA' in current package

[hadley]

Right, there's no .Rd file so there's nothing to inherit from. I don't think this is something we want to support.

[gaborcsardi]

@nlneas1 FWIW roxygen2 supports code execution via the usual markdown notation:

this is text `r r-expression` more text

Not the same as inheritance, but could work for your problem.

[nlneas1]

Thanks @gaborcsardi. The problem I currently have is I have a worker function which is used by multiple other functions, e.g.

funWorker <- function(a, b, c, d = c("option1", "option2", "option3"))

funA <- function(a, b, c) funWorker(a, b, c, d = "option1")
funB <- function(a, b, c) funWorker(a, b, c, d = "option2")
funC <- function(a, b, c) funWorker(a, b, c, d = "option3")

etc. As funWorker() is internal to the package, I don't want to have to document parameters a, b and c in three separate places. FWIW, it absolutely does make sense for me to have three separate help files - one for each of funA, funB and funC.

I would have though that @noRd would still generate the file such that inheritance can take place in the parser and then clear out the help files which contain @noRd at the end.

[nlneas1]

I think code execution is only really helpful for quickly executing functionality and only when you have objects in scope. It's not ideal for when you are dealing with Spark, for instance, and have objects stored in the a cloud space such as Azure or AWS.

[nlneas1]

@hadley if this isn't going to be supported, might I suggest this interaction (or lack thereof) is documented? Apologies if it already is, but I didn't see it anywhere and as a user, the internals of how @inheritParams is not immediately obvious to me.

[kevinushey]

I do something like this in renv:

https://github.com/rstudio/renv/blob/4a8bcb4605f085fbea5f29a76ad9a291ac2bd363/R/roxygen.R#L2-L26

Basically, you have an roxygen block associated with NULL, but give it an explicit @name -- then @inheritParams can reference that name, even if no .Rd is generated for the "source" of those params.

https://github.com/rstudio/renv/blob/4a8bcb4605f085fbea5f29a76ad9a291ac2bd363/R/embed.R#L11

[nlneas1]

Thanks @kevinushey - this is perfect and works really nicely. For anyone looking to use this in the future, make sure you don't include a title since that will generate the .Rd file (at least on 6.1.1), you just need to include the @param and @name tags. From there you can @inheritParams from the @name name.

So in the example above, I would have

#' @param a This is a parameter
#' @param b This is a parameter
#' @param c This is a parameter
#' @param d This is what separates the functions
#'
#' @name funWorkerParams
NULL

Then you can document the individual functions as normal

#' Function A
#' @inheritParams funWorkerParams
#' @export
funA <- function(a, b, c) {
  funWorker(a, b, c, d = "option1")
}

You will receive the following warning message, but you can ignore it:

Warning messages:
1: funWorker.Rd is missing name/title. Skipping