Experiment utility function to display docstring-esque help for R functions in Global Environment

help2.R

# Experimental utility function

message("--------------------------------------------------------------------------------\n")
message("Overwriting `?` function with custom utility to display in memory function help.\n")
message("--------------------------------------------------------------------------------\n\n")

help2 = function(f, ...) {
  #' Extend `help()` to show in memory function documentation
  #'
  #' @details Supports python docstring-esque roxygen documentation.
  #'          Function will be searched for in `globalenv()` and
  #'          inline roxygen documentation will be printed if found.
  #'          If not found, regular `help()` will be run.
  #'
  #' @param f function name to show help for
  #' @param ... additional args to be passed to `help()`
  #' @return NULL
  #'
  #' @examples
  #' sq = function(x) {
  #'   #' Square a number
  #'   #'
  #'   #' @param x number to square
  #'   #' @return x squared
  #'   #'
  #'   #' @examples
  #'   #' sq(2) == 4
  #'   x * x
  #' }
  #'
  #' help2(help)  # Display normal help for `help()`
  #' help2(sq)    # `cat()` roxygen docs in console
  if (!(is.character(f) & length(f) == 1)) {
    f = as.character(substitute(f))
  }
  
  # Attempt to print roxygen comments from f in `globalenv()`
  if (f %in% ls(envir = globalenv())) {
    try({
      f_fun = get(f, envir = globalenv())
      f_body = capture.output(print(f_fun))
      body_help_contents = grep("^#'", trimws(f_body), value = TRUE)
      body_help_contents = gsub("^#'", "", body_help_contents)
      
      display_body_help_contents = paste0(paste(body_help_contents, collapse = "\n"), "\n")
      
      if (trimws(display_body_help_contents) != "") {
        cat(display_body_help_contents)
        return(invisible())
      }
    }, silent = TRUE)
  }
  
  # Perform normal help process and display if successful
  print(help(f, ...))
  return(invisible())
}


`?` = function(f, ignored) {
  #' Extend `help()` to show in memory function documentation
  #'
  #' @details Supports python docstring-esque roxygen documentation.
  #'          Function will be searched for in `globalenv()` and
  #'          inline roxygen documentation will be printed if found.
  #'          If not found, regular `help()` will be run.
  #'
  #' @param f function name to show help for
  #' @param ignored parameter ignored
  #'
  #' @return NULL
  #'
  #' @examples
  #' sq = function(x) {
  #'   #' Square a number
  #'   #'
  #'   #' @param x number to square
  #'   #' @return x squared
  #'   #'
  #'   #' @examples
  #'   #' sq(2) == 4
  #'   x * x
  #' }
  #'
  #' ?help  # Display normal help for `help()`
  #' ?sq    # `cat()` roxygen docs in console
  
  f_name_str = as.character(substitute(f))
  
  if (length(f_name_str) == 3 & f_name_str[1] %in% c(":::", "::")) {
    help2(f_name_str[3], package = f_name_str[2])
  } else {
    help2(f_name_str)
  }
}