Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

@inheritParams with NULL doc targets #836

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

@inheritParams with NULL doc targets #836

kenahoo opened this issue Dec 26, 2018 · 5 comments

Comments

@kenahoo
Copy link

@kenahoo 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:

  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
Copy link
Member

@hadley 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
Copy link
Member

@hadley 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)

@hadley hadley closed this in a4abe1d Aug 22, 2019
@kenahoo
Copy link
Author

@kenahoo 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
Copy link
Member

@hadley 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
Copy link
Author

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

dill added a commit to DistanceDevelopment/Distance that referenced this issue Jun 22, 2020
traversc pushed a commit to traversc/qs that referenced this issue Nov 24, 2021
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants