add examples and return value explanations to exported functions (#311)

Author: cjyetman

R/analyse.R

@@ -3,17 +3,26 @@
 #' @description
 #' `analyse()` runs the necessary steps to analyse the matched loan books,
 #' producing both the outputs of the standard PACTA analysis and the outputs of
-#' the net aggregated alignment metric, including tables and plots.
-#' Parameters for all steps are read from a `config.yml` file. The function is
-#' called for its side effects and writes the prepared and diagnosed data sets
-#' to the directory `output/analysis`, where `output` is the
-#' output directory  specified in the `config.yml`.
+#' the net aggregated alignment metric, including tables and plots. Parameters
+#' for all steps are read from a `config.yml` file. The function is called for
+#' its side effects and writes the prepared and diagnosed data sets in the
+#' directory specified by `dir_analysis` in the `config.yml`.
 #'
 #' `analyse()` and `analyze()` are synonyms.
 #'
 #' @param config either a path to a config.yml file or a list of parameters
 #'
-#' @return NULL
+#' @return
+#'
+#' `analyse()` returns `NULL` invisibly. The function is called for its side
+#' effects and writes the prepared and diagnosed data sets in the directory
+#' specified by `dir_analysis` in the `config.yml`.
+#'
+#' @examples
+#' \dontrun{
+#' config <- "path/to/config.yml"
+#' analyse(config)
+#' }
 #'
 #' @export
 

R/initialise_default_project.R

@@ -1,9 +1,24 @@
 #' Initialise a project directory and its config file
 #'
+#' @description
+#' `initialise_default_project()` sets up a default project directory, including
+#' a project directory, a default `config.yml` configuration file, an `input`
+#' sub-directory, and a `loanbooks` sub-directory.
+#'
 #' @param path an absolute or relative path pointing to the location you would
 #'   like the project directory to be created
 #'
-#' @returns NULL
+#' @return
+#'
+#' `initialise_default_project()` returns `NULL` invisibly. The function is
+#' called for its side effects of creating a default project directory at the
+#' specified path.
+#'
+#' @examples
+#' \dontrun{
+#' project_dir <- "path/to/project"
+#' initialise_default_project(project_dir)
+#' }
 #'
 #' @export
 

R/match_loanbooks.R

@@ -9,12 +9,21 @@
 #' processing. Parameters for the matching step are read from a `config.yml`
 #' file and follow the options available in `r2dii.match::match_name`. The
 #' function is called for its side effects and writes the prepared data sets to
-#' the directory `output/match`, where `output` is the output directory
-#' specified in the `config.yml`.
+#' the directory specified by `dir_matched_loanbooks` in the `config.yml`.
 #'
 #' @param config either a path to a config.yml file or a list of parameters
 #'
-#' @return NULL
+#' @return
+#'
+#' `match_loanbooks()` returns `NULL` invisibly. The function is called for its
+#' side effects and writes the prepared data sets to the directory specified by
+#' `dir_matched_loanbooks` in the `config.yml`.
+#'
+#' @examples
+#' \dontrun{
+#' config <- "path/to/config.yml"
+#' match_loanbooks(config)
+#' }
 #'
 #' @export
 

R/prepare_abcd.R

@@ -4,15 +4,24 @@
 #' `prepare_abcd()` runs the necessary steps to prepare the input data sets for
 #' the PACTA for Supervisors analysis. Specifically it prepares the abcd_final
 #' data set by removing inactive companies if desired. And it allows preparing
-#' the ratios by which the exposures to counterparties are split along the sectors.
-#' Parameters for both steps are read from a `config.yml` file. The function is
-#' called for its side effects and writes the prepared data sets to the directory
-#' `output/prepare`, where `output` is the output directory specified in the
-#' `config.yml`.
+#' the ratios by which the exposures to counterparties are split along the
+#' sectors. Parameters for both steps are read from a `config.yml` file. The
+#' function is called for its side effects and writes the prepared data sets in
+#' the directory specified by `dir_prepared_abcd` in the `config.yml`.
 #'
 #' @param config either a path to a config.yml file or a list of parameters
 #'
-#' @return NULL
+#' @return
+#'
+#' `prepare_abcd()` returns `NULL` invisibly. The function is called for its
+#' side effects and writes the prepared data sets in the directory specified by
+#' `dir_prepared_abcd` in the `config.yml`.
+#'
+#' @examples
+#' \dontrun{
+#' config <- "path/to/config.yml"
+#' prepare_abcd(config)
+#' }
 #'
 #' @export
 

R/prioritise_and_diagnose.R

@@ -1,19 +1,29 @@
 #' Prioritise and diagnose the loan book data sets used in the PACTA for Supervisors analysis
 #'
 #' @description
-#' `prioritise_and_diagnose()` runs the necessary steps to prioritise the matched
-#' loan books and diagnose both the match success rate and the coverage of the
-#' real economy assets by the matched loan books.
-#' Parameters for all steps are read from a `config.yml` file. The function is
-#' called for its side effects and writes the prepared and diagnosed data sets
-#' to the directory `output/prioritise_and_diagnose`, where `output` is the
-#' output directory  specified in the `config.yml`.
+#' `prioritise_and_diagnose()` runs the necessary steps to prioritise the
+#' matched loan books and diagnose both the match success rate and the coverage
+#' of the real economy assets by the matched loan books. Parameters for all
+#' steps are read from a `config.yml` file. The function is called for its side
+#' effects and writes the prepared and diagnosed data sets in the directory
+#' specified by `dir_prioritized_loanbooks_and_diagnostics` in the `config.yml`.
 #'
 #' `prioritise_and_diagnose()` and `prioritize_and_diagnose()` are synonyms.
 #'
 #' @param config either a path to a config.yml file or a list of parameters
 #'
-#' @return NULL
+#' @return
+#'
+#' `prioritise_and_diagnose()` returns `NULL` invisibly. The function is called
+#' for its side effects and writes the prepared and diagnosed data sets in the
+#' directory specified by `dir_prioritized_loanbooks_and_diagnostics` in the
+#' `config.yml`.
+#'
+#' @examples
+#' \dontrun{
+#' config <- "path/to/config.yml"
+#' prioritise_and_diagnose(config)
+#' }
 #'
 #' @export