By Peng Zhao | June 15, 2018
The documentation level of R is already much higher than average for open source software and even than some commercial packages (esp. SPSS is notorious for its attitude of "You want to do one of these things. If you don't understand what the output means, click help and we'll pop up five lines of mumbo-jumbo that you're not going to understand either.")
-- Peter Dalgaard
R-help (April 2002)
Although the R package beginr is published on CRAN, its documentation is insufficient, only because beginr was submitted to CRAN too soon and I had no time to improve the documentation.
The documentation of a function in an R package could be displayed by running the
help() function. For example, the documentation of the
errorbar()function in beginr can be displayed when running:
Then the user will see the following information:
Description add error bars to a scatterplot. Usage errorbar(x, y, xupper = NULL, xlower = NULL, yupper = NULL, ylower = NULL, col = "black", lty = 1) Arguments x numeric y numeric xupper numeric xlower numeric yupper numeric ylower numeric col colors lty numeric Value errorbars in a plot Examples x <- seq(0, 2 * pi, length.out = 100) y <- sin(x) plot(x, y, type = "l") errorbar(x, y, yupper = 0.1, ylower = 0.1)
The Description, Usage and Argument are too brief. As beginr is developed for R beginners, a detailed documentation would help.
A desired example of the documentation for an R function can be found when running the following function:
A detailed documentation will appear as follows:
Standard Deviation Description This function computes the standard deviation of the values in x. If na.rm is TRUE then missing values are removed before computation proceeds. Usage sd(x, na.rm = FALSE) Arguments x a numeric vector or an R object which is coercible to one by as.double(x). na.rm logical. Should missing values be removed? Details Like var this uses denominator n - 1. The standard deviation of a zero-length vector (after removal of NAs if na.rm = TRUE) is not defined and gives an error. The standard deviation of a length-one vector is NA. See Also var for its square, and mad, the most robust alternative. Examples sd(1:2) ^ 2
The task is to write a friendly documentation for each function in beginr.
The suggested tool is RStudio. Open 'R/foo.R' (this file name is stupid and I will change it later) with a text editor (RStudio is recommended), and add the documentation in the header of each function. After the documentation is done, I will re-build the package, then the 'man/*.Rd' files will be updated automatically.
Each function will have a detailed help information from the documentation.
Open 'R/foo.R' with a text editor. Each function begins with a short description, followed by several lines beginning with
#', then the function body . For example, the
errorbar() function begins at line 198, and looks like this:
#' add error bars to a scatterplot. #' #' @param x numeric #' @param y numeric #' @param xupper numeric #' @param xlower numeric #' @param yupper numeric #' @param ylower numeric #' @param col colors #' @param lty numeric #' #' @return errorbars in a plot #' @export #' @examples #' x <- seq(0, 2 * pi, length.out = 100) #' y <- sin(x) #' plot(x, y, type = 'l') #' errorbar(x, y, yupper = 0.1, ylower = 0.1) #' errorbar <- function(x, y, ......
The first line 'add error bars to a scatterplot' is a short description about the function
errorbar(). This description is sufficient. However, the lines beginning with
#' @param are not sufficiently documented. For instance, line 200:
#' @param x numeric
only mentions that x should be numeric. A desired documentation for this line should be written as:
#' @param x A numeric vector plotted as the coordinates of points.
which is much better and more friendly to users.
I would suggest that this task had better be claimed by an R user, because most of the '@param' lines are self-explanatory to an R expert. He/she could run the function
example(function_name) to test each function in beginr, and get to understand what these parameters are really are.