docs: add return options for report functions

R/IV_report.R

@@ -6,19 +6,24 @@
 #' @title Generate a Information Value HTML Report
 #'
 #' @description
-#' The function generates an interactive HTML report using
-#' Standard Person Query data as an input. The report contains a full Information Value analysis,  a data exploration technique that helps determine which columns in a data set have predictive power or influence on the value of a specified dependent variable.
+#' The function generates an interactive HTML report using Standard Person Query
+#' data as an input. The report contains a full Information Value analysis,  a
+#' data exploration technique that helps determine which columns in a data set
+#' have predictive power or influence on the value of a specified dependent
+#' variable.
 #'
 #' @param data A Standard Person Query dataset in the form of a data frame.
-#' @param predictors A character vector specifying the columns to be used as predictors.
-#' Defaults to NULL, where all numeric vectors in the data will be used as predictors.
+#' @param predictors A character vector specifying the columns to be used as
+#'   predictors. Defaults to NULL, where all numeric vectors in the data will be
+#'   used as predictors.
 #' @param outcome A string specifying a binary variable, i.e. can only contain
-#' the values 1 or 0.
-#' @param bins Number of bins to use in `Information::create_infotables()`, defaults to 10.
-#' @param path Pass the file path and the desired file name, _excluding the file extension_.
-#' For example, "collaboration report".
-#' @param timestamp Logical vector specifying whether to include a timestamp in the file name.
-#' Defaults to TRUE.
+#'   the values 1 or 0.
+#' @param bins Number of bins to use in `Information::create_infotables()`,
+#'   defaults to 10.
+#' @param path Pass the file path and the desired file name, _excluding the file
+#'   extension_. For example, "collaboration report".
+#' @param timestamp Logical vector specifying whether to include a timestamp in
+#'   the file name. Defaults to TRUE.
 #'
 #' @examples
 #' \dontrun{
@@ -30,6 +35,8 @@
 #' @family Reports
 #' @family Information Value
 #'
+#' @inherit generate_report return
+#'
 #' @export
 IV_report <- function(data,
                       predictors = NULL,

R/capacity_report.R

@@ -26,6 +26,8 @@
 #'
 #' @family Reports
 #'
+#' @inherit generate_report return
+#'
 #' @export
 capacity_report <- function(data,
                             hrvar = "Organization",

R/coaching_report.R

@@ -26,6 +26,8 @@
 #'
 #' @family Reports
 #'
+#' @inherit generate_report return
+#'
 #' @export
 coaching_report <- function(data,
                             hrvar = "LevelDesignation",

R/collaboration_report.R

@@ -25,6 +25,8 @@
 #'
 #' @family Reports
 #'
+#' @inherit generate_report return
+#'
 #' @export
 collaboration_report <- function(data,
                                  hrvar = "Organization",

R/connectivity_report.R

@@ -26,6 +26,8 @@
 #'
 #' @family Reports
 #'
+#' @inherit generate_report return
+#'
 #' @export
 connectivity_report <- function(data,
                                 hrvar = "LevelDesignation",

R/generate_report.R

@@ -26,19 +26,28 @@
 #'
 #' @family Reports
 #'
-#' @examples
-#' \dontrun{
+#' @section Creating a custom report:
+#'
+#' Below is an example on how to set up a custom report.
+#'
+#' The first step is to define the content that will go into a report and assign
+#' the outputs to a list.
+#' ```
 #' # Step 1: Define Content
 #' output_list <-
 #'   list(sq_data %>% workloads_summary(return = "plot"),
-#'        sq_data %>%
-#'          workloads_summary(return = "table")) %>%
+#'        sq_data %>% workloads_summary(return = "table")) %>%
 #'   purrr::map_if(is.data.frame, create_dt)
-#'
+#' ```
+#' The next step is to add a list of titles for each of the objects on the list:
+#' ```
 #' # Step 2: Add Corresponding Titles
 #' title_list <- c("Workloads Summary - Plot", "Workloads Summary - Table")
 #' n_title <- length(title_list)
-#'
+#' ```
+#' The final step is to run `generate_report()`. This can all be wrapped within
+#' a function such that the function can be used to generate a HTML report.
+#' ```
 #' # Step 3: Generate Report
 #' generate_report(title = "My First Report",
 #'                 filename = "My First Report",
@@ -46,8 +55,12 @@
 #'                 titles = title_list,
 #'                 subheaders = rep("", n_title),
 #'                 echos = rep(FALSE, n_title
+#' ```
+#' @return
+#' An HTML report with the same file name as specified in the arguments is
+#' generated in the working directory. No outputs are directly returned by the
+#' function.
 #'
-#' }
 #' @export
 generate_report <- function(title = "My minimal HTML generator",
                             filename = "minimal_html",

R/meeting_tm_report.R

@@ -13,6 +13,9 @@
 #' @param seed A numeric vector to set seed for random generation.
 #'
 #' @family Text-mining
+#' @family Reports
+#'
+#' @inherit generate_report return
 #'
 #' @export
 meeting_tm_report <- function(data,

R/subject_validate_report.R

@@ -10,6 +10,8 @@
 #' Returns a HTML report by default.
 #'
 #' @family Data Validation
+#' @family Text-mining
+#' @family Reports
 #'
 #' @param data A Meeting Query dataset in the form of a data frame.
 #' @param path Pass the file path and the desired file name, _excluding the file extension_.
@@ -19,8 +21,10 @@
 #' @param keep A numeric vector specifying maximum number of words to keep.
 #' @param seed A numeric vector to set seed for random generation.
 #'
+#'
+#' @inherit generate_report return
+#'
 #' @export
-
 subject_validate_report <- function(data,
                               path = "Subject Lines Validation Report",
                               timestamp = TRUE,

R/workpatterns_report.R

@@ -18,6 +18,8 @@
 #' @param timestamp Logical vector specifying whether to include a timestamp in
 #'   the file name. Defaults to TRUE.
 #'
+#' @inherit generate_report return
+#'
 #' @importFrom purrr map_if
 #' @importFrom methods is
 #'

man/IV_report.Rd

@@ -16,23 +16,33 @@ IV_report(
 \arguments{
 \item{data}{A Standard Person Query dataset in the form of a data frame.}
 
-\item{predictors}{A character vector specifying the columns to be used as predictors.
-Defaults to NULL, where all numeric vectors in the data will be used as predictors.}
+\item{predictors}{A character vector specifying the columns to be used as
+predictors. Defaults to NULL, where all numeric vectors in the data will be
+used as predictors.}
 
 \item{outcome}{A string specifying a binary variable, i.e. can only contain
 the values 1 or 0.}
 
-\item{bins}{Number of bins to use in \code{Information::create_infotables()}, defaults to 10.}
+\item{bins}{Number of bins to use in \code{Information::create_infotables()},
+defaults to 10.}
 
-\item{path}{Pass the file path and the desired file name, \emph{excluding the file extension}.
-For example, "collaboration report".}
+\item{path}{Pass the file path and the desired file name, \emph{excluding the file
+extension}. For example, "collaboration report".}
 
-\item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
-Defaults to TRUE.}
+\item{timestamp}{Logical vector specifying whether to include a timestamp in
+the file name. Defaults to TRUE.}
+}
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
 }
 \description{
-The function generates an interactive HTML report using
-Standard Person Query data as an input. The report contains a full Information Value analysis,  a data exploration technique that helps determine which columns in a data set have predictive power or influence on the value of a specified dependent variable.
+The function generates an interactive HTML report using Standard Person Query
+data as an input. The report contains a full Information Value analysis,  a
+data exploration technique that helps determine which columns in a data set
+have predictive power or influence on the value of a specified dependent
+variable.
 }
 \examples{
 \dontrun{
@@ -49,6 +59,8 @@ Other Reports:
 \code{\link{collaboration_report}()},
 \code{\link{connectivity_report}()},
 \code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{validation_report}()}
 
 Other Information Value: 

man/capacity_report.Rd

@@ -26,6 +26,11 @@ For example, "capacity report".}
 \item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
 Defaults to TRUE.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 The function generates an interactive HTML report using the
 Standard Person Query data as an input. The report contains a series
@@ -40,6 +45,8 @@ Other Reports:
 \code{\link{collaboration_report}()},
 \code{\link{connectivity_report}()},
 \code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{validation_report}()}
 }
 \concept{Reports}

man/coaching_report.Rd

@@ -26,6 +26,11 @@ For example, "collaboration report".}
 \item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
 Defaults to TRUE.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 The function generates an interactive HTML report using
 Standard Person Query data as an input. The report contains a series
@@ -40,6 +45,8 @@ Other Reports:
 \code{\link{collaboration_report}()},
 \code{\link{connectivity_report}()},
 \code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{validation_report}()}
 }
 \concept{Reports}

man/collaboration_report.Rd

@@ -26,6 +26,11 @@ For example, "collaboration report".}
 \item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
 Defaults to TRUE.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 The function generates an interactive HTML report using
 Standard Person Query data as an input. The report contains a series
@@ -39,6 +44,8 @@ Other Reports:
 \code{\link{coaching_report}()},
 \code{\link{connectivity_report}()},
 \code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{validation_report}()}
 }
 \concept{Reports}

man/connectivity_report.Rd

@@ -26,6 +26,11 @@ For example, "collaboration report".}
 \item{timestamp}{Logical vector specifying whether to include a timestamp in the file name.
 Defaults to TRUE.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 The function generates an interactive HTML report using
 Standard Person Query data as an input. The report contains a series
@@ -40,6 +45,8 @@ Other Reports:
 \code{\link{coaching_report}()},
 \code{\link{collaboration_report}()},
 \code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{validation_report}()}
 }
 \concept{Reports}

man/generate_report.Rd

@@ -37,33 +37,44 @@ E.g. "united", "default".}
 
 \item{preamble}{A preamble to appear at the beginning of the report, passed as a text string.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 This is a support function using a list-pmap workflow to
 create a HTML document, using RMarkdown as the engine.
 }
-\examples{
-\dontrun{
-# Step 1: Define Content
+\section{Creating a custom report}{
+
+
+Below is an example on how to set up a custom report.
+
+The first step is to define the content that will go into a report and assign
+the outputs to a list.\preformatted{# Step 1: Define Content
 output_list <-
   list(sq_data \%>\% workloads_summary(return = "plot"),
-       sq_data \%>\%
-         workloads_summary(return = "table")) \%>\%
+       sq_data \%>\% workloads_summary(return = "table")) \%>\%
   purrr::map_if(is.data.frame, create_dt)
+}
 
-# Step 2: Add Corresponding Titles
+The next step is to add a list of titles for each of the objects on the list:\preformatted{# Step 2: Add Corresponding Titles
 title_list <- c("Workloads Summary - Plot", "Workloads Summary - Table")
 n_title <- length(title_list)
+}
 
-# Step 3: Generate Report
+The final step is to run \code{generate_report()}. This can all be wrapped within
+a function such that the function can be used to generate a HTML report.\preformatted{# Step 3: Generate Report
 generate_report(title = "My First Report",
                 filename = "My First Report",
                 outputs = output_list,
                 titles = title_list,
                 subheaders = rep("", n_title),
                 echos = rep(FALSE, n_title
+}
+}
 
-}
-}
 \seealso{
 Other Reports: 
 \code{\link{IV_report}()},
@@ -71,6 +82,8 @@ Other Reports:
 \code{\link{coaching_report}()},
 \code{\link{collaboration_report}()},
 \code{\link{connectivity_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{validation_report}()}
 }
 \concept{Reports}

man/meeting_tm_report.Rd

@@ -28,14 +28,31 @@ Defaults to TRUE.}
 
 \item{seed}{A numeric vector to set seed for random generation.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 Create a text mining report in HTML based on Meeting Subject Lines
 }
 \seealso{
 Other Text-mining: 
+\code{\link{subject_validate_report}()},
 \code{\link{tm_clean}()},
 \code{\link{tm_cooc}()},
 \code{\link{tm_freq}()},
 \code{\link{tm_wordcloud}()}
+
+Other Reports: 
+\code{\link{IV_report}()},
+\code{\link{capacity_report}()},
+\code{\link{coaching_report}()},
+\code{\link{collaboration_report}()},
+\code{\link{connectivity_report}()},
+\code{\link{generate_report}()},
+\code{\link{subject_validate_report}()},
+\code{\link{validation_report}()}
 }
+\concept{Reports}
 \concept{Text-mining}

man/subject_validate_report.Rd

@@ -25,6 +25,11 @@ Defaults to TRUE.}
 
 \item{seed}{A numeric vector to set seed for random generation.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 This functions creates a text mining report in HTML based on Meeting Subject Lines for data validation. It scans a meeting query and highlights meetings with subjects that include common exlusion terms. It is intended to be used by an analyst to validate raw data before conducting additional analysis.
 Returns a HTML report by default.
@@ -48,5 +53,24 @@ Other Data Validation:
 \code{\link{remove_outliers}()},
 \code{\link{subject_validate}()},
 \code{\link{track_HR_change}()}
+
+Other Text-mining: 
+\code{\link{meeting_tm_report}()},
+\code{\link{tm_clean}()},
+\code{\link{tm_cooc}()},
+\code{\link{tm_freq}()},
+\code{\link{tm_wordcloud}()}
+
+Other Reports: 
+\code{\link{IV_report}()},
+\code{\link{capacity_report}()},
+\code{\link{coaching_report}()},
+\code{\link{collaboration_report}()},
+\code{\link{connectivity_report}()},
+\code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{validation_report}()}
 }
 \concept{Data Validation}
+\concept{Reports}
+\concept{Text-mining}

man/tm_clean.Rd

@@ -24,6 +24,7 @@ The default is to return a data frame with tokenised counts of words or ngrams.
 \seealso{
 Other Text-mining: 
 \code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{tm_cooc}()},
 \code{\link{tm_freq}()},
 \code{\link{tm_wordcloud}()}

man/tm_cooc.Rd

@@ -38,6 +38,7 @@ mt_data \%>\%
 \seealso{
 Other Text-mining: 
 \code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{tm_clean}()},
 \code{\link{tm_freq}()},
 \code{\link{tm_wordcloud}()}

man/tm_freq.Rd

@@ -38,6 +38,7 @@ tm_freq(mt_data, token = "ngrams")
 \seealso{
 Other Text-mining: 
 \code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{tm_clean}()},
 \code{\link{tm_cooc}()},
 \code{\link{tm_wordcloud}()}

man/tm_wordcloud.Rd

@@ -48,6 +48,7 @@ tm_wordcloud(mt_data, keep = 30)
 \seealso{
 Other Text-mining: 
 \code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()},
 \code{\link{tm_clean}()},
 \code{\link{tm_cooc}()},
 \code{\link{tm_freq}()}

man/validation_report.Rd

@@ -83,6 +83,8 @@ Other Reports:
 \code{\link{coaching_report}()},
 \code{\link{collaboration_report}()},
 \code{\link{connectivity_report}()},
-\code{\link{generate_report}()}
+\code{\link{generate_report}()},
+\code{\link{meeting_tm_report}()},
+\code{\link{subject_validate_report}()}
 }
 \concept{Reports}

man/workpatterns_report.Rd

@@ -32,6 +32,11 @@ extension}. For example, "scope report".}
 \item{timestamp}{Logical vector specifying whether to include a timestamp in
 the file name. Defaults to TRUE.}
 }
+\value{
+An HTML report with the same file name as specified in the arguments is
+generated in the working directory. No outputs are directly returned by the
+function.
+}
 \description{
 \ifelse{html}{\out{<a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a>}}{\strong{Experimental}}