[R-pkg-devel] A replacement idiom for \value{\item{\var{...}}{}}

[Ivan Krylov]

Hello R-package-devel,

I've got a function that returns a data.frame. The columns (and their
names) of the return value are parametrised by the arguments of the
function. See, for example, the following function:

foo <- function(n = 10, out.M = c(2, 3, 5))
 as.data.frame(setNames(
  lapply(out.M, \(M) M * runif(n)),
  paste0('fooval.', out.M)
 ))

If I call it as foo(out.M = 1), I get a data.frame containing a column
named fooval.1. If I call it as foo(), I get columns fooval.2,
fooval.3, and fooval.5 instead.

I would like to document this relationship between the arguments and
the output value like so:

\arguments{
 \item{out.M}{Return the foo vectors for every M value given here.}
 % more arguments that behave in a similar manner
}
% ...
\value{
 A \code{data.frame} containing the following columns:

 \item{fooval.\var{m}}{
  The foo values, for every \var{m} in \code{out.M}.
 }
 % more parametrised output columns to follow
}

It turns out that \value{} description lists now escape their \item{}
arguments, preventing me from using \var{} markup there, but only in
plain text and HTML outputs. I think that the change occurred in the
last year or so; old versions of R process markup in \item{} arguments
even in \value{} description lists, but they have other Rd problems. I
understand the motivation of the change: in \arguments{} and \value{}
environments, it makes sense to typeset \item{} headings as \code{}.

Should I try to fix Rd2latex (or at least file a ticket) to escape the
\item{...} arguments in \value{} (but not \describe{}!) environments
too?

What would be a better Rd idiom for such function argument — output
component relationships?

-- 
Best regards,
Ivan