{{ message }}

# @inheritParams with NULL doc targets#836

Closed
opened this issue Dec 26, 2018 · 5 comments
Closed

# @inheritParams with NULL doc targets#836

opened this issue Dec 26, 2018 · 5 comments
Labels
Milestone

### kenahoo commented Dec 26, 2018

 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: How can I get this working as desired? 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.) The text was updated successfully, but these errors were encountered:

### hadley commented Jul 20, 2019

 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 commented Aug 22, 2019

 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)

closed this in  a4abe1d  Aug 22, 2019

### kenahoo commented Aug 22, 2019

 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 commented Aug 22, 2019

 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 commented Aug 22, 2019

 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.

added a commit to DistanceDevelopment/Distance that referenced this issue Jun 22, 2020
 add parameters manually to new doco items 
 086fa0c 
due to this issue: r-lib/roxygen2#836
mentioned this issue Nov 7, 2021
pushed a commit to traversc/qs that referenced this issue Nov 24, 2021
 Improve roxygen2 usage 
 1232868 
Rely on various modern roxygen2 features to simplify and streamline documentation and reduce duplications. There were also a bunch of documentation errors/mistakes that this PR fixes as well as various spelling harmonizations.

Note that unfortunately we can't use @inheritParams [since](r-lib/roxygen2#836 (comment))

> 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.

Instead we use @eval to minimize duplication, cf. https://roxygen2.r-lib.org/articles/rd.html#evaluating-arbitrary-code

Also note that Markdown support in roxygen2 documentation tags is now enabled globally for the whole package which means percentage signs mustn't be escaped anymore.