allow minidesc sections for "Methods (by generic)" AND "Functions"

[maxheld83]

I'm trying to document a class constructor, as well as its methods (for external generics) and some other (convenience) function in one document.

As per the vignette, I'm using @describeIn for the purpose, which gives very helpful mini descriptions for each of the methods or functions in separate sections.

However, it appears that roxygen will only accept one type (either bunch of methods per generic, or a bunch of functions) via @describeIn.

This works:

#library(ggplot2)

#' @title Class constructor
#' @description I construct classes for a living.
#' @param x Always an expressive argument name.
myClassName <- function(x) {
  class(x) <- "myClassName"
  return(x)
}

#' @describeIn myClassName Plot `myClassName` objects via ggplot2.
#' @param object a [myClassName] object, created by [myClassName()].
autoplot.myClassName <- function(object) {
  # just placeholder code
  g <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
  return(g)
}

#' @rdname myClassName
#' @param bar other format to provide `x` maybe
other_fun <- function(bar) {
  return(bar)
}

However, when I include the other_fun() via @describeIn – which yields a more accessible documentation:

#library(ggplot2)

#' @title Class constructor
#' @description I construct classes for a living.
#' @param x Always an expressive argument name.
myClassName <- function(x) {
  class(x) <- "myClassName"
  return(x)
}

#' @describeIn myClassName Plot `myClassName` objects via ggplot2.
#' @param object a [myClassName] object, created by [myClassName()].
autoplot.myClassName <- function(object) {
  # just placeholder code
  g <- ggplot(mtcars, aes(wt, mpg)) + geom_point()
  return(g)
}

#' @describeIn myClassName Some other function.
#' @param bar other format to provide `x` maybe
other_fun <- function(bar) {
  return(bar)
}

Documenting fails with:

Error: identical(x$type, y$type) is not TRUE
Execution halted

Exited with status 1.

This error message seems to stem from here, which disallows different types: stopifnot(identical(x$type, y$type)).

I can, however, manually, edit the resulting myClassName.Rd to add another section, without build errors:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/test.R
\name{myClassName}
\alias{myClassName}
\alias{autoplot.myClassName}
\alias{other_fun}
\title{Class constructor}
\usage{
myClassName(x)

\method{autoplot}{myClassName}(object)

other_fun(bar)
}
\arguments{
\item{x}{Always an expressive argument name.}

\item{object}{a \link{myClassName} object, created by \code{\link[=myClassName]{myClassName()}}.}

\item{bar}{other format to provide \code{x} maybe}
}
\description{
I construct classes for a living.
}
\section{Methods (by generic)}{
\itemize{
\item \code{autoplot}: Plot \code{myClassName} objects via ggplot2.
}}
\section{Functions}{
\itemize{
\item \code{other_fun}: Do something else.
}}

So I am assuming that this is a limitation of roxygen not of R documentations as such.

Any chance multiple types for minidesc could be supported?

I know this is a fairly edge case.

To justify this niche scenario: It would just be quite nice to document methods for some class and associated functions (say, functions with return myNewClass, but work with a different/more convenient input format) in the same place.

[hadley]

Minimal reprex:

library(roxygen2)

out <- roc_proc_text(rd_roclet(), "
  #' Generic
  foo <- function(x) UseMethod('foo')
  
  #' @describeIn foo related function
  bar <- function(y) {}
")[[1]]
#> Warning: file4315ca5c357:6: Don't know how to describe function in
#> s3generic
#> Warning: bar.Rd is missing name/title. Skipping

^{Created on 2019-09-11 by the reprex package (v0.3.0)}