Is there a sensible way to do something like docstrings in R? [closed]

Question

This is not just a coding style question. If you know python (and I think also Ruby has something like this), you can have a docstring in a function, such that you can readily get that string by issuing a "help" command. e.g.:

def something(t=None):     '''Do something, perhaps to t      t : a thing         You may not want to do this     '''     if t is not None:         return t ** 2     else:         return 'Or maybe not' 

Then help(something) returns the following:

Help on function something in module __main__:  something(t=None)     Do something, perhaps to t      t : a thing         You may not want to do this 

The way things work in R, you can get the full text of the defined code snippet, so you could see comments (including those at the beginning of the function), but that can be a lot of scrolling and visual filtering. Is there any better way?

Answer 1

I recently wrote a package to do just this task. The docstring package allows one to write their documentation as roxygen style comments within the function they are documenting. For example one could do

square <- function(x){     #' Square a number      return(x^2) } 

and then to view the documentation either call the docstring function

docstring(square) 

or use the built in ? support and do

?square 

The comments can either be a single chunk like shown above or fully roxygen style to take advantage of some of the keywords provided

square <- function(x){      #' Square a number     #'     #' Calculates the square of the input     #'     #' @param x the input to be squared      return(x^2) } 

This is on CRAN now: https://cran.r-project.org/package=docstring so you can just install using

install.packages("docstring") 

or if you want the latest development version you can install from github:

library(devtools) install_github("dasonk/docstring") 

Answer 2

You can add any attributes you like to R objects, including function. So something like

describe <- function(obj) attr(obj, "help") foo <- function(t=NULL) ifelse(!is.null(t), t^2, "Or maybe not") attr(foo, "help") <- "Here is the help message" 

produces more or less the desired output

> foo(2) [1] 4 > foo() [1] "Or maybe not" > describe(foo) [1] "Here is the help message"