Description
This was already partially addressed #666. (It was probably only partially addressed because I had failed to provide a reprex).
As per #666 and the below test, you can now document other functions via @describeIn
for generics:
roxygen2/tests/testthat/test-rd-describe-in.R
Lines 72 to 82 in b3053b6
However, this fallback isn't triggered when you @describeIn
methods and other functions together:
library(roxygen2)
out <- roc_proc_text(rd_roclet(), "
#' Generic
# foo <- function(x) {}
foo <- function(x) UseMethod('foo')
#' @describeIn foo some method
as.character.zap <- function(x) c('zap')
#' @describeIn foo related function
bar <- function(y) {}
")[[1]]
yields:
Error in merge.rd_section_minidesc(self$get_section(type), section) :
identical(x$value$type, y$value$type) is not TRUE
Whether the "parent" function (the function you're @describeIn
in) is a normal function or a generic does not seem to matter.
You can trigger the same error with:
library(roxygen2)
out <- roc_proc_text(rd_roclet(), "
#' Normal
foo <- function(x) {}
#' @describeIn foo some method
as.character.zap <- function(x) c('zap')
#' @describeIn foo related function
bar <- function(y) {}
")[[1]]
Motivation
I think this scenario might sometimes happen when documenting new (S3) OO schemes.
For example, you might have a class, and wish to document some (say, print) methods with it, as well as some "normal" functions, such as a validator.
More Background
(Not necessary to debug this, but might be helpful to other people who run into this and are confused about the relationship to vctrs::s3_register()
You can also run into this problem if you wish to expand other generics (say, knitr::knit_print()
, which you don't want to @ImportFrom
(and therefore Imports:
in your DESCRIPTION
).
If you then place knitr in your Suggests:
and dynamically vctrs::s3_register()
knit_print
in your onLoad
, your newly minted method knit_print.foo()
will then look (to roxygen anyway) as a normal function, and will therefore trigger the above error.