Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
maxheld83 opened this issue Sep 14, 2017 · 4 comments
Closed

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

maxheld83 opened this issue Sep 14, 2017 · 4 comments

Comments

@maxheld83
Copy link
Member

@maxheld83 maxheld83 commented Sep 14, 2017

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.

@stufield

This comment has been hidden.

billdenney added a commit to billdenney/formulops that referenced this issue Oct 28, 2018
@billdenney

This comment has been hidden.

@hadley

This comment has been hidden.

@hadley
Copy link
Member

@hadley hadley commented Sep 11, 2019

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants