@describeIn throws error when used with S4 methods.

[ralmond]

I thought a perfect example of a use of @describeIn was describing generic functions and methods in a class definition.

So here is a code snippet which I thought would work:

#'
#'
#' This is a lightweight class meant to be extended.  It contains a
#' single field for a mongo identifier, which can be accessed using
#' the `m_id()` method.  It is meant to store something that is a
#' record in a mongo collection, where `_id` is the mongo identifier.
#'
#'
#'
#' @name MongoRec-class
#' @aliases MongoRec-class m_id,MongoRec-method m_id<-,MongoRec-method
#' as.jlist,MongoRec,list-method as.json,MongoRec-method
#' @docType class
#' @section Objects from the Class:
#'
#' Objects can be created by calls to the \code{\link{MongoRec}()} function.
#' @author Russell G. Almond
#' @seealso \code{\link{MongoRec}()} --- constructor
#' \code{\link{as.json}},
#' \code{\link{parseObject}}, \code{\link{saveRec}}, \code{\link{getOneRec}}
#' @keywords classes
#' @examples
#'
#' showClass("MongoRec")
#'
#' @exportClass("MongoRec")
setClass("MongoRec",
         slots=c("_id"="character"    #Mongo ID
                 ))
#' @describeIn MongoRec Accessor for Mongo id.
setGeneric("m_id",function(x) standardGeneric("m_id"))

#' @describeIn MongoRec Accessor for Mongo id.
setGeneric("m_id<-",function(x, value) standardGeneric("m_id<-"))

#' @describeIn MongoRec Accessor for Mongo id.
setMethod("m_id","MongoRec", function(x) x@"_id")

#' @describeIn MongoRec  Accessor for Mongo id.
setMethod("m_id<-","MongoRec", function(x,value) {
  names(value) <- "oid"
  x@"_id" <- value
  x})

However, I get

Error in merge.rd_section_minidesc(self$get_section(type), section) : 
  identical(x$value$type, y$value$type) is not TRUE

(This is the same error referenced in my previous issue, about there not being sufficient context information with the error).

However, I think this should be a case where @describeIn works (or at least it needs better documentation as to what works and why).

Note, I get a similiar error, if I move the documentation to the m_id generic function and try to use @describeIn m_id for the other generic and the two methods.

[hadley]

Would you minding having a go at creating a reprex following the advice in https://github.com/r-lib/roxygen2/blob/main/.github/SUPPORT.md#making-a-reprex ?

[ralmond]

library(roxygen2)
roc_proc_text(rd_roclet(),"
#' Class \\dQuote{MongoRec}
#'
setClass('MongoRec',
         slots=c('_id'='character'    #Mongo ID
                 ))
                 
#' @describeIn MongoRec Accessor for Mongo id.
setGeneric('m_id',function(x) standardGeneric('m_id'))

#' @describeIn MongoRec Accessor for Mongo id.
setMethod('m_id','MongoRec', function(x) x@'_id')

")
#> Error in merge.rd_section_minidesc(self$get_section(type), section): identical(x$value$type, y$value$type) is not TRUE

Here you go. The issue appears to be related to having a generic function and a method both documented in the same object.

[hadley]

Now we get a better warning, but should consider supporting this:

library(roxygen2)
x <- roc_proc_text(rd_roclet(),"
#' Class \\dQuote{MongoRec}
#'
setClass('MongoRec',
         slots=c('_id'='character'    #Mongo ID
                 ))
                 
#' @describeIn MongoRec Accessor for Mongo id.
setGeneric('m_id',function(x) standardGeneric('m_id'))

#' @describeIn MongoRec Accessor for Mongo id.
setMethod('m_id','MongoRec', function(x) x@'_id')

")
#> Warning: [<text>:12] Don't know how to combine @describeIn types "function" and
#> "class"

^{Created on 2022-07-10 by the reprex package (v2.0.1)}

[hadley]

That PR makes it work, but it doesn't give particularly nice labels so re-opening.

[hadley]

With current PR:

library(roxygen2)
roc_proc_text(rd_roclet(),"
#' Class \\dQuote{MongoRec}
#'
setClass('MongoRec',
         slots=c('_id'='character'    #Mongo ID
                 ))
                 
#' @describeIn MongoRec Accessor for Mongo id.
setGeneric('m_id',function(x) standardGeneric('m_id'))

#' @describeIn MongoRec Accessor for Mongo id.
setMethod('m_id','MongoRec', function(x) x@'_id')

")[[1]]
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \docType{class}
#> \name{MongoRec-class}
#> \alias{MongoRec-class}
#> \alias{m_id}
#> \alias{m_id,MongoRec-method}
#> \title{Class \dQuote{MongoRec}}
#> \usage{
#> m_id(x)
#> 
#> \S4method{m_id}{MongoRec}(x)
#> }
#> \description{
#> Class \dQuote{MongoRec}
#> }
#> \section{Methods (by generic)}{
#> \itemize{
#> \item \code{m_id(MongoRec)}: Accessor for Mongo id.
#> 
#> }}
#> \section{Functions}{
#> \itemize{
#> \item \code{m_id()}: Accessor for Mongo id.
#> 
#> }}

^{Created on 2022-07-16 by the reprex package (v2.0.1)}