Repository
https://github.com/pzhaonet/beginr
Details
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:
library('beginr')
help(errorbar)
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:
help(sd)
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.
Components
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.
Deadline
30 June, 2018.
Communication
- Submit a pull request to 'github.com/pzhaonet/beginr' (recommended),
- open an issue to 'github.com/pzhaonet/beginr' (recommended),
- reply to this post, or
- send an email to pzhao@pzhao.net