9 Add documentation

So we noticed that there was nothing in learned when we looked at it - the reason is that we need to export the functions. To do this, we need to document our functions using roxygen2.

In short, roxygen2 provides us with nifty syntax to give documentation to our functions, which also allows them to be exported.

Let’s demonstrate with boxplot_study_state.R:

It starts like this:

boxplot_study_state <- function(data) {
  ggplot2::ggplot(
    data,
    ggplot2::aes(
      x = prop_studying,
      y = state_territory
    )
  ) +
    ggplot2::geom_boxplot()
}

And we can add a “roxygen skeleton” by going to code > insert roxygen skeleton (or with Alt/Option + Ctrl/Cmd + Shift + R) whilst our cursor is in the function, and we get this:

#' Title
#'
#' @param data 
#'
#' @returns
#' @export
#'
#' @examples
boxplot_study_state <- function(data) {
  ggplot2::ggplot(
    data,
    ggplot2::aes(
      x = prop_studying,
      y = state_territory
    )
  ) +
    ggplot2::geom_boxplot()
}

Which we can then populate:

#' Provide a boxplot of study data
#'
#' @param data data from education 2014
#'
#' @returns a ggplot object
#' @export
#'
#' @examples
#' # no example data yet
boxplot_study_state <- function(data) {
  ggplot2::ggplot(
    data,
    ggplot2::aes(
      x = prop_studying,
      y = state_territory
    )
  ) +
    ggplot2::geom_boxplot()
}

We then call document(), which gives us the output:

ℹ Updating learned documentation
ℹ Loading learned
Writing NAMESPACE
Writing boxplot_study_state.Rd

This allows us to look at the documented function with ?boxplot_study_state.

This function also gets added to the NAMESPACE file.

Here’s the commit of that

Note three things:

NAMESPACE now has boxplot_study_state.R in it
We have added some roxygen code
There’s some LaTeX looking code in man/boxplot_study_state.Rd

Your Turn

Repeat this process for all the remaining functions in learned
1. add the roxygen skeleton
2. population the roxygen skeleton
3. run document()

See this commit to see what this looks like when done.

So now we have some functions in our package! Woo!

For fun, try looking at the documentation with ?clean_age_groups

What’s missing from these functions? Examples! For examples, we need our data! Let’s add that to the package.