Do you want to be able to read function documentation for your own functions? Make your own package.
I have noted at least one instance (and there are probably others) about how Python
’s docStrings are so great, and wouldn’t it be nice to have a similar system in R
. Especially when you can have your new function tab completion available depending on your development environment.
This is a false statement, however. If you set up your R
development environment properly, you can have these features available in R
. It will take a little bit of work, however.
This approach heavily depends on devtools
and roxygen2
.
I do recommend using the RStudio
IDE, as much of what I am discussing is very much integrated into the IDE itself. However, much of what I discuss is applicable regardless of what development environment you use.
First off, you probably want to put your functions into packages. Really, it’s not that hard. A DESCRIPTION
file, NAMESPACE
, and an R
directory with your function definitions. If you are using RStudio
, then you can create a new project as a package. Alternatively, you can set up a new package directory using package.skeleton
.
If you are using RStudio
, I recommend setting your package options:
roxygen
(roxygen2)
Rd
files on Build & Reload
)Whenever you make changes to your package functions, you simply commit
(you are using version control, right??), and then Build & Reload
(if using RStudio
) or install()
if using devtools
.
For documentation that lives with your functions, I heavily recommend using roxygen2
. Although the normal way to document stuff in R
is through the use of Rd
files, roxygen2
allows you to put the following in your R\functions.r
file:
#' this is a silly function
#' @param input1 this is an input to our function
#' @param input2 this is another input
#' @return some value
#' @export
<- function(input1, input2){
sillyFunction
FunctionBody }
When you do Build & Reload
(or install
), the required Rd
file will be generated automatically, and upon Reload
ing the package, you will have full access to your documentation, and tab completion of your new function, along with descriptions of the parameters if you are using RStudio
. Note, if you are not using RStudio
, then you should do document
to re-generate Rd
files prior to doing install
.
This particular workflow is how I now work in R
, for almost every project that includes any self written functions, including analysis projects. Why I use this (and not another format such as ProjectTemplate) is another post, hopefully soon.
Updated 2014.02.21: Note that the original post mentioned roxygen
instead of roxygen2
. Thanks Carl for pointing that out. You should use roxygen2
for documentation.
If you see mistakes or want to suggest changes, please create an issue on the source repository.
Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/rmflight/researchBlog_distill, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".
For attribution, please cite this work as
Flight (2014, Feb. 20). Deciphering Life: One Bit at a Time: Self-Written Function Help. Retrieved from https://rmflight.github.io/posts/2014-02-20-self-written-function-help/
BibTeX citation
@misc{flight2014self-written, author = {Flight, Robert M}, title = {Deciphering Life: One Bit at a Time: Self-Written Function Help}, url = {https://rmflight.github.io/posts/2014-02-20-self-written-function-help/}, year = {2014} }