@inheritParams with NULL doc targets

[kenahoo]

I have the following docs:

#' First function
#'
#' @name funcOne
#' @rdname funcOne
#' @usage
#' funcOne(name,
#'         deps)
#'
#' @param name name of the artifact
#' @param deps names of other artifacts this artifact depends on
NULL

#' Second function
#'
#' @name funcTwo
#' @rdname funcTwo
#' @usage
#' funcTwo(name,
#'         deps,
#'         create,
#'         ...)
#'
#' @inheritParams funcOne  // TODO Doesn't work yet
#' @param create function to create this artifact object from its dependency objects
#' @param ... further arguments passed to \code{\link{foo}}
NULL

The @inheritParams directive doesn't have the desired effect, no parameters are inherited from funcOne:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/docs-test.R
\name{funcTwo}
\alias{funcTwo}
\title{Second function}
\usage{
funcTwo(name,
        deps,
        create,
        ...)
}
\arguments{
\item{create}{function to create this artifact object from its dependency objects}

\item{...}{further arguments passed to \code{\link{foo}}}
}
\description{
Second function
}

Some notes:

• If I change @inheritParams to something bogus like @inheritTheWind, I get a proper Warning: @inheritTheWind [/Users/kwilliams/git/GroveR/R/docs-test.R#25]: unknown tag, so I do know the original tag is at least being recognized as legitimate
• If I change @inheritParams funcOne to a bogus @inheritParams foo, no warning is printed - this makes me suspect my original example is silently not finding the funcOne parameters too.

So two questions:

1. How can I get this working as desired?
2. When @inheritParams can't find the specified target, can it spit out a warning/error that might help track down the problem?

Thanks.

(NB- this issue adapted from #835. I'm trying to use this NULL style of docs because the things I'm documenting are actually R6 objects defined a particular way.)

[hadley]

roxygen2 doesn't parse the usage block, so it doesn't know what the usage is, and hence it doesn't find any parameters to inherit. I think we could make this a warning.

[hadley]

Minimal reprex:

library(roxygen2)
out <- roc_proc_text(rd_roclet(), "
  #' First function
  #'
  #' @name fun1
  #' @usage fun1(x)
  #' @param x x
  NULL
  
  #' Second function
  #'
  #' @name fun2
  #' @usage fun2(x, y)
  #' @inheritParams fun1
  NULL
")

^{Created on 2019-08-22 by the reprex package (v0.3.0)}

[kenahoo]

Thanks for creating the reprex, I didn't have enough knowledge to know how.

As for inheriting params when using a @usage block, it seems like there are two ways to go, both of which require changes to roxygen:

• Parse the @usage block to figure out what params are required. Would be rather easy, and a warning could be issued if parsing failed.
• Add an @inheritParam param func to explicitly inherit a parameter from another chunk. Seems like it would be a bit of a hassle to use this way, though.

Other ideas? Or recent techniques for documenting R6 objects I might have missed?

[hadley]

I don't think it's worth building out a bunch of special purpose functionality to support documenting R6 objects; instead it would be better to build a standard way of documenting R6 objects.

[kenahoo]

Seems good in theory, but there's not really even a standard way of creating R6 objects, which seems like it would make roxygen's job of auto-parsing it out of the code kind of tough. Maybe there's some way to standardize both of them together and make the whole schmeer more pleasant. I've thought about working on "nicer" ways to create R6 stuff but haven't done much yet.