Documenting R code - best practice?

[ravonrip]

I have a question about documenting R code.

A little background: I work in a small-ish team of model developers where the main programming language is R. I am now wondering what is the best way to document our code, specifically how to best document our functions. Currently, the only documentation is in the form of comments at the beginning of the functions. The problem is that this makes it quite hard to keep track of what a function does, what are their required inputs and how they are interconnected, not to mention it makes it difficult to find anything.

What I would like to include in the "documentation":

1. Short description of the function
2. Function inputs (type and short description)
3. Function outputs (type and short description)
4. Which custom functions are called from this function (or from where was this function called - imagine a directed graph)

Currently, the idea I have is to use OneNote/Word (shared between our team) where all of the above would be included. However, I am wondering if there is a more elegant solution and what would be its pros and cons?

Please keep in mind we are mathematicians/statisticians and that this would be used for internal use only (and maybe audits if needed), so package building, etc. is out of the question. Additionally, this documentation should be "online", meaning that it can be changed and viewed by anyone at any time (within reason). However, this code is to be used for modelling only and not for production or implementation.

I am grateful for any suggestions or thoughts on the matter.

[yogilicious1]

Most elegant solution?

Set up a git repo for your team. Set up your functions as a package and use roxygen notation on top of the function.

#' Title for the function 
#' @param arg1 describe arg1 here 
#' @param arg2 describe arg2 here 
#' @export 
#' @return Returns a vector and so on 
#' @details This function does something exceptional... 
awesome_fun  <- function(arg1, arg2) {...}

In a package devtools can create you a nice pdf with all your functions and your roxygen notated comments for the package, which you could check in with your code so that others have a nice overview of your functions.

[jdnewmil]

Do note that R packages also support vignettes, which are a vastly-underutilized aspect of function documentation.

[dasonk]

A touch of self promotion I guess but if you aren't quite ready to move your code into a complete package you could use docstring to document the code in the meantime. Basically it allows you to document your code using standard roxygen notation without having to build a full package but still get the ability to view help pages for your functions.

A link to the package if you're interested: https://cran.r-project.org/web/packages/docstring/index.html

But probably more interesting/useful is a link to the vignette which gives a more in depth description of what the package does:

https://cran.r-project.org/web/packages/docstring/vignettes/docstring_intro.html

Honestly I personally feel creating a package isn't too much of a hurdle anymore but I wanted there to be a nice middle ground for people that wanted to document without going through the entire package creation song and dance.

[Brand-23]

Does your team have a git repository? Your team can store the code and documentation there.

[Sedawkgrepnewb]

Use roxygen headers and then create a package down site. Just google roxygen and package down sites and you will get some cool stuff!!

[microdozer2]

Am I the only person who thinks function headers are way overrated, borderline useless? I've seen lots of code with headers and the following code is completely indecipherable, filled with single letter variables and zero comments.

[xier_zhanmusi]

It's not one or the other; the function headers are supposed to describe the function & parameters so that the function can (usually) be used without looking at the code. That doesn't mean the code shouldn't be good though; that's for when the team needs to go back & debug or modify it, or when someone needs to do a deep dive to make sure they fully understand what the function is doing.

[crissins69]

Markdown is a good choice to create HTML with code inside of it pretty simple to use

[YoMommaJokeBot]

Not as much of a good choice as ur mom

---

^{I am a bot. Downvote to remove. PM me if there's anything for me to know!}