Skip to content

@describeIn fails when used on S3 method and other funs together #1181

Closed
@maxheld83

Description

@maxheld83

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:

test_that("all other combinations fallback to function list", {
out <- roc_proc_text(rd_roclet(), "
#' Generic
foo <- function(x) UseMethod('foo')
#' @describeIn foo related function
bar <- function(y) {}
")[[1]]
expect_equal(out$get_value("minidesc")$type, "function")
})

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featurea feature request or enhancementrd ✍️

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions