Function commenting conventions in R

Question

I'm fairly new to R, and I have been defining some of my own functions in script files. I'm intending for others to re-use them later, and I can't find any guides on R function commenting conventions. Is there any way for me to make help("my_function_name") show some help? If not, do I just document the function in the script file, so that someone has to print out (or open the source of) a script to see the comments?

Thanks,

Hamy

Lynx

Answer 1

Updating this question December 2019 as the R-universe has changed since 2011 when originally written

My recommended resource is now http://r-pkgs.had.co.nz/

Original answer (links are mostly out of date)

The canonical way to document your functions and make them accessible to others is to make a package. In order for your package to pass the build checks, you have to supply sufficiently detailed help files for each of your functions / datasets.

Check out http://cran.r-project.org/doc/manuals/R-exts.html#Creating-R-packages

This blog post from Rob J Hyndman was very useful and one of the easiest for me to follow: http://robjhyndman.com/researchtips/building-r-packages-for-windows/

I've started using roxygen to assist in making & compiling packages as of late: http://roxygen.org/

Lots of good resources and people to help when you have questions!

Pejorative

The link to the blog post of Rob J Hyndman is broken. Alternatively, the pdf can now be found here. – Unrig

The 2nd and 3rd urls are 404 – Mcmahan

@Mcmahan - I added a new reference that's accurate as of 2019...impressive this question still gets traction nearly a decade later. – Pejorative

Answer 2

Another (and lower key) alternative you could look into are the comment() and attr() functions to add some meta data to your functions. Here's a quick and silly example:

FOO <- function(x,y) {
 x + y 
}

attr(FOO, "comment") <- "FOO performs simple addition"

#This can be arbitrary. "comment" is special. see ?comment for details.
attr(FOO, "help") <- "FOO expects two numbers, and it will add them together"

You can then see everything associated with FOO by using attributes():

> attributes(FOO)
$source
[1] "function(x,y) {" " x + y "         "}"              

$comment
[1] "FOO performs simple addition"

$help
[1] "FOO expects two numbers, and it will add them together"

Or extract specific parts:

> attr(FOO, "help")
[1] "FOO expects two numbers, and it will add them together"
attr(FOO, "comment")
[1] "FOO performs simple addition"

And in the case of comment, use comment():

> comment(FOO)
[1] "FOO performs simple addition"

In the long term, writing your own package will almost certainly be worth the overhead and time investment, but if for some reason that isn't practical in the short term - here's another option.

Pejorative

+1 I do this all the time, especially for saved workspaces and functions that aren't overly complicated but you want to know "what they do" quickly. – Prostomium

Answer 3

You will have to put functions into a package (which makes porting function REALLY easy). I have written a short post about it a while ago with links (I hope they still work) to some relevant documents that expand the subject.

You can generate help files "on the fly" using roxygen, inlinedocs.

Aerate

Is that a roxygen echo? echo? – Pejorative

Answer 4

If you are not building a package, you can use docstring package, which offers similar functions as Python's docstring.

library(docstring)

square <- function(x){

    #' Square a number
    #'
    #' Calculates the square of the input
    #'
    #' @param x the input to be squared

    return(x^2)
}

You can see the comments by calling ?square. output

This tutorial might be helpful.

Infracostal