7.2.0 breaks a pattern for inheriting parameters to S4 methods from the class generic's help

[MichaelChirico]

See here for a minimal example:

https://github.com/MichaelChirico/roxygen2S4inheritsError

In words, the upstream package implements a generic myGeneric, and downstream implements a character method for that generic.

We simply want to copy the documentation of the generic to the method, so we use @inheritParams upstream::myGeneric.

Previously (in 7.1.2), this "just works", but it's broken by switching to 7.2.0:

Loading required package: upstream
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Warning: @inherits failed in topic "myGeneric,character-method".
✖ Can't find topic upstream::myGeneric.
Error in get_rd_from_help(pkg, fun, source) : 
  argument "source" is missing, with no default
Calls: Main ... <Anonymous> -> glue_data -> <Anonymous> -> %||% -> .transformer
Execution halted

I'm not sure why upstream::myGeneric isn't found; ?upstream::myGeneric displays the expected topic.

Any workaround or fix would be great.

[hadley]

Just looking at the code, it uses help <- utils::help(alias, (package)) to find the topic, so it's not obvious why that might be failing.

[hadley]

I can't reproduce the problem with devtools::install("upstream"); devtools::document("downstream")

[hadley]

(Although I can't reproduce it, I do see why the final error occurs and it should be fixed now)

[hadley]

Oh I can reproduce it with devtools::load_all("upstream"); devtools::document("downstream"). That's not surprising since dev docs aren't available through the usual help lookup.

[hadley]

And the change is https://github.com/r-lib/roxygen2/pull/1311/files#diff-119940ba0ac6f4274ac43a8888075a1c7e1384c21640164c55e1f27d09198dbaL391 — probably because eval() ends up using the help() shimmed by devtools. I can just switch it back I think.

[hadley]

Hmmm, switching it back doesn't help because utils:::.getHelpFile() doesn't work with the result returned by dev_help. So I'm mystified as to why this ever worked.

[MichaelChirico]

Is 974243881c3aefd033659ebeb387d7736b781fe1 a commit I should be able to cherry pick in isolation to see if this fixes our problem?

Or should I wait for further updates?

[hadley]

No, that’ll just give you a better warning instead of an error at the end. You could try reverting https://github.com/r-lib/roxygen2/pull/1311/files#diff-119940ba0ac6f4274ac43a8888075a1c7e1384c21640164c55e1f27d09198dbaL391.

How are you loading the packages? Is it likely that load_all() is in the mix?

[MichaelChirico]

How are you loading the packages?

it's complicated -- our build system is a strange beast. load_all() won't be involved though

it is possible it's entirely our fault for doing something unexpected, but I thought I reproduced on my own machine too

[hadley]

This seems like a fairly subtle problem so I'm going to drop from the upcoming patch release (since I need to get it out soon for some HTML generation fixes for CRAN), but I'm happy to keep looking into it. I do think I'll need more of a reprex from your end though.

[MichaelChirico]

a workaround would also be fine -- what's the right way to use @inheritParams on an S4 generic? any examples you could point to?

[hadley]

You are using it correctly; as far as I can it's something with the way that you're loading/installing packages that's causing the problem. roxygen2 uses help() to find the path to the appropriate .Rd file to inherit from and something about what you're doing is breaking that.

[MichaelChirico]

thanks, I'll investigate more and post any findings.

[MichaelChirico]

Hmm our bug seems to have gone away. I'm not sure when exactly the fix landed, but my best guess is when we fixed an issue where the broken package was mistakenly using tags like

#' @inherit dbDefineTable
#' @inherit methods::show
#' @inherit dplyr db_save_query

(of course these should be @importFrom)

Leaving open for now in case that inspires any friendlier error handling that could have averted the confusion here, but feel free to close. Thanks!

[hadley]

Closing since no further correspondence in the last 12 months, and seems to be ok on your end.