Documentation

There are three areas of documentation in the new data system, and all are required.

Function (chunk) documentation

All functions in the gcamdata package are documented using roxygen2, special comments before each function that are rendered into R's built-in help system. This means a user can easily view a help page:

library(gcamdata)
?driver
help(package = "gcamdata")

For example, the driver's roxygen2 comment block looks like this:

#' driver
#'
#' Run the entire data system.
#'
#' @param all_data Data to be pre-loaded into data system
#' @param write_outputs Write all chunk outputs to disk?
#' @param quiet Suppress output?
#' @return A list of all built data.
#' @details The driver loads any necessary data from input files,
#' runs all code chunks in an order dictated by their dependencies,
#' does error-checking, and writes outputs. For more details, see
#' the relevant wiki page at \url{ https://github.com/bpbond/gcamdata/wiki/Driver}.
#' @importFrom magrittr "%>%"
#' @importFrom assertthat assert_that
#' @export
#' @author BBL

This provides the name of the object and a brief one-sentence summary; descriptions of all parameters and return values; implementation details; what functions should be imported from other namespaces because they're needed; a flag signaling that this function should be exported, i.e. be publicly available; and the author. For most chunks, all of these fields are required.

Code documentation

TODO

Data documentation

Input csv files are required to be documented as described here: https://github.com/JGCRI/gcamdata/wiki/Input-Files

TODO - Other types of data

  # Convert to long form, filter to historical years, convert units
  usda_gdp_mer %>%
    ...
    select(-Country) %>%
    add_dscomments(c("Historical GDP downscaled to country (iso)",
                     "Unit = million 1990 US dollars")) %>%
    # flag that this dataset is in different form from original
    add_dsflags(FLAG_LONG_FORM, FLAG_NO_XYEAR) ->
    L100.gdp_mil90usd_ctry_Yh