Convenience function to generate roxygen comment blocks

[eheinzen]

It'd be nice to have a convenience function to create roxygen comment blocks automatically. This would be similar to utils::prompt, but instead of creating Rd files, it would print out roxygen comment blocks Perhaps make it S3, with methods for functions and data.frames? I'm thinking something like this:

> myfun <- function(a, b, ..., d) NULL
> use_roxygen_comments(myfun)
#' <Title>
#' 
#' <Description>
#' 
#' @param a <parameter description>
#' @param b <parameter description>
#' @param ... <parameter description>
#' @param d <parameter description>
#' @return <describe returned object
#' @seealso <links to other help pages>
#' @export

[eheinzen]

Maybe something as easy as this:

use_roxygen_comments <- function(x, ...)
{
  UseMethod("use_roxygen_comments")
}

use_roxygen_comments.function <- function(x, ...)
{
  x <- match.fun(x)
  nms <- names(formals(x))
  if(length(nms) > 0) {
    params <- paste0("@param ", nms, " <parameter description>")
  } else {
    params <- character(0)
  }

  txt <- c("<Title>", "", "<Description>", "", params, "@return <describe returned object",
           "@seealso <links to other help pages>", "@export")
  out <- paste0("#' ", txt)
  cat(out, sep = '\n')
  invisible(out)
}

[jimhester]

The RStudio IDE already supports this code->Insert Roxygen Skeleton, but presumably you are using a different editor?

[eheinzen]

Thanks, Jim. I'm on RStudio and saw that, but this was suggested by a coworker. Many people are still using emacs, etc., for their editing...

[hadley]

This is out of scope for usethis - and is duplicate of r-lib/roxygen2#253