docs: return options (#31)

R/afterhours_dist.R

@@ -14,11 +14,9 @@
 #' Uses the metric \code{After_hours_collaboration_hours}.
 #' See `create_dist()` for applying the same analysis to a different metric.
 #'
-#' @param data A Standard Person Query dataset in the form of a data frame.
-#' @param hrvar HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation"
-#' @param mingroup Numeric value setting the privacy threshold / minimum group size, defaults to 5.
-#' @param return Character vector specifying what to return, defaults to "plot".
-#' Valid inputs are "plot" and "table".
+#' @inheritParams create_dist
+#' @inherit create_dist return
+#'
 #' @param cut A vector specifying the cuts to use for the data,
 #' accepting "default" or "range-cut" as character vector,
 #' or a numeric value of length three to specify the exact breaks to use. e.g. c(1, 3, 5)

R/create_bar.R

@@ -16,14 +16,24 @@
 #' @param hrvar HR Variable by which to split metrics, defaults to "Organization"
 #' but accepts any character vector, e.g. "LevelDesignation"
 #' @param mingroup Numeric value setting the privacy threshold / minimum group size. Defaults to 5.
-#' @param return Character vector specifying what to return, defaults to "plot".
-#' Valid inputs are "plot" and "table".
+#'
+#' @param return String specifying what to return. This must be one of the following strings:
+#'   - `"plot"`
+#'   - `"table"`
+#'
+#' See `Value` for more information.
+#'
 #' @param bar_colour String to specify colour to use for bars.
-#' In-built accepted values include "default" (default), "alert" (red), and
-#' "darkblue". Otherwise, hex codes are also accepted. You can also supply
+#' In-built accepted values include `"default"` (default), `"alert"` (red), and
+#' `"darkblue"`. Otherwise, hex codes are also accepted. You can also supply
 #' RGB values via `rgb2hex()`.
-#' @param na.rm A logical value indicating whether NA values should be stripped
-#' before the computation proceeds. Defaults to FALSE.
+#' @param na.rm A logical value indicating whether `NA` should be stripped
+#' before the computation proceeds. Defaults to `FALSE`.
+#'
+#' @return
+#' A different output is returned depending on the value passed to the `return` argument:
+#'   - `"plot"`: ggplot object. A bar plot for the metric.
+#'   - `"table"`: data frame. A summary table for the metric.
 #'
 #' @import dplyr
 #' @import ggplot2
@@ -33,10 +43,6 @@
 #'
 #' @family General
 #'
-#' @return
-#' Returns a ggplot object by default, where 'plot' is passed in `return`.
-#' When 'table' is passed, a summary table is returned as a data frame.
-#'
 #' @examples
 #' # Return a ggplot bar chart
 #' create_bar(sq_data, metric = "Collaboration_hours", hrvar = "LevelDesignation")

R/create_dist.R

@@ -11,18 +11,28 @@
 #' Additional options available to return a table with distribution elements.
 #'
 #' @param data A Standard Person Query dataset in the form of a data frame.
-#' @param metric Character string containing the name of the metric,
+#' @param metric String containing the name of the metric,
 #' e.g. "Collaboration_hours"
 #' @param hrvar HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation"
 #' @param mingroup Numeric value setting the privacy threshold / minimum group size, defaults to 5.
-#' @param return Character vector specifying what to return, defaults to "plot".
-#' Valid inputs are "plot" and "table".
+#'
+#' @param return String specifying what to return. This must be one of the following strings:
+#'   - `"plot"`
+#'   - `"table"`
+#'
+#' See `Value` for more information.
+#'
 #' @param cut A numeric vector of length three to specify the breaks for the distribution,
 #' e.g. c(10, 15, 20)
 #' @param dist_colours A character vector of length four to specify colour
 #' codes for the stacked bars.
 #' @param unit See `cut_hour()`.
 #'
+#' @return
+#' A different output is returned depending on the value passed to the `return` argument:
+#'   - `"plot"`: ggplot object. A stacked bar plot for the metric.
+#'   - `"table"`: data frame. A summary table for the metric.
+#'
 #' @import dplyr
 #' @import ggplot2
 #' @import reshape2

R/create_fizz.R

@@ -18,8 +18,16 @@
 #' e.g. "Collaboration_hours"
 #' @param hrvar HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation"
 #' @param mingroup Numeric value setting the privacy threshold / minimum group size, defaults to 5.
-#' @param return Character vector specifying what to return, defaults to "plot".
-#' Valid inputs are "plot" and "table".
+#' @param return String specifying what to return. This must be one of the following strings:
+#'   - `"plot"`
+#'   - `"table"`
+#'
+#' See `Value` for more information.
+#'
+#' @return
+#' A different output is returned depending on the value passed to the `return` argument:
+#'   - `"plot"`: ggplot object. A jittered scatter plot for the metric.
+#'   - `"table"`: data frame. A summary table for the metric.
 #'
 #' @import dplyr
 #' @import ggplot2

man/afterhours_dist.Rd

@@ -19,13 +19,25 @@ afterhours_dist(
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A vector specifying the cuts to use for the data,
 accepting "default" or "range-cut" as character vector,
 or a numeric value of length three to specify the exact breaks to use. e.g. c(1, 3, 5)}
 }
+\value{
+A different output is returned depending on the value passed to the \code{return} argument:
+\itemize{
+\item \code{"plot"}: ggplot object. A stacked bar plot for the metric.
+\item \code{"table"}: data frame. A summary table for the metric.
+}
+}
 \description{
 Analyse the distribution of weekly after-hours collaboration time.
 Returns a stacked bar plot by default.

man/afterhours_fizz.Rd

@@ -13,8 +13,13 @@ afterhours_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot")
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Analyze weekly after-hours collaboration hours distribution, and returns

man/afterhours_summary.Rd

@@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \value{
 Returns a ggplot object by default, where 'plot' is passed in \code{return}.

man/collaboration_dist.Rd

@@ -37,8 +37,13 @@ collaboration_distribution(
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A numeric vector of length three to specify the breaks for the distribution,
 e.g. c(10, 15, 20)}

man/collaboration_fizz.Rd

@@ -16,8 +16,13 @@ collab_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot")
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Analyze weekly collaboration hours distribution, and returns

man/create_bar.Rd

@@ -25,20 +25,28 @@ but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{bar_colour}{String to specify colour to use for bars.
-In-built accepted values include "default" (default), "alert" (red), and
-"darkblue". Otherwise, hex codes are also accepted. You can also supply
+In-built accepted values include \code{"default"} (default), \code{"alert"} (red), and
+\code{"darkblue"}. Otherwise, hex codes are also accepted. You can also supply
 RGB values via \code{rgb2hex()}.}
 
-\item{na.rm}{A logical value indicating whether NA values should be stripped
-before the computation proceeds. Defaults to FALSE.}
+\item{na.rm}{A logical value indicating whether \code{NA} should be stripped
+before the computation proceeds. Defaults to \code{FALSE}.}
 }
 \value{
-Returns a ggplot object by default, where 'plot' is passed in \code{return}.
-When 'table' is passed, a summary table is returned as a data frame.
+A different output is returned depending on the value passed to the \code{return} argument:
+\itemize{
+\item \code{"plot"}: ggplot object. A bar plot for the metric.
+\item \code{"table"}: data frame. A summary table for the metric.
+}
 }
 \description{
 Provides an overview analysis of a selected metric by calculating a mean per metric.

man/create_dist.Rd

@@ -18,15 +18,20 @@ create_dist(
 \arguments{
 \item{data}{A Standard Person Query dataset in the form of a data frame.}
 
-\item{metric}{Character string containing the name of the metric,
+\item{metric}{String containing the name of the metric,
 e.g. "Collaboration_hours"}
 
 \item{hrvar}{HR Variable by which to split metrics. Accepts a character vector, defaults to "Organization" but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A numeric vector of length three to specify the breaks for the distribution,
 e.g. c(10, 15, 20)}
@@ -36,6 +41,13 @@ codes for the stacked bars.}
 
 \item{unit}{See \code{cut_hour()}.}
 }
+\value{
+A different output is returned depending on the value passed to the \code{return} argument:
+\itemize{
+\item \code{"plot"}: ggplot object. A stacked bar plot for the metric.
+\item \code{"table"}: data frame. A summary table for the metric.
+}
+}
 \description{
 Provides an analysis of the distribution of a selected metric.
 Returns a stacked bar plot by default.

man/create_fizz.Rd

@@ -22,8 +22,20 @@ e.g. "Collaboration_hours"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
+}
+\value{
+A different output is returned depending on the value passed to the \code{return} argument:
+\itemize{
+\item \code{"plot"}: ggplot object. A jittered scatter plot for the metric.
+\item \code{"table"}: data frame. A summary table for the metric.
+}
 }
 \description{
 Analyzes a selected metric and returns a a 'fizzy' scatter plot by default.

man/email_dist.Rd

@@ -19,8 +19,13 @@ email_dist(
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A numeric vector of length three to specify the breaks for the distribution,
 e.g. c(10, 15, 20)}

man/email_fizz.Rd

@@ -13,8 +13,13 @@ email_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot")
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Analyze weekly email hours distribution, and returns

man/email_summary.Rd

@@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \value{
 Returns a ggplot object by default, where 'plot' is passed in \code{return}.

man/meeting_dist.Rd

@@ -19,8 +19,13 @@ meeting_dist(
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A numeric vector of length three to specify the breaks for the distribution,
 e.g. c(10, 15, 20)}

man/meeting_fizz.Rd

@@ -13,8 +13,13 @@ meeting_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot")
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Analyze weekly meeting hours distribution, and returns

man/meeting_summary.Rd

@@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \value{
 Returns a ggplot object by default, where 'plot' is passed in \code{return}.

man/one2one_dist.Rd

@@ -19,8 +19,13 @@ one2one_dist(
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A numeric vector of length three to specify the breaks for the distribution,
 e.g. c(10, 15, 20)}

man/one2one_fizz.Rd

@@ -13,8 +13,13 @@ one2one_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot")
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Analyze weekly Manager 1:1 Time distribution, and returns

man/one2one_sum.Rd

@@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \value{
 Returns a ggplot object by default, where 'plot' is passed in \code{return}.

man/workloads_dist.Rd

@@ -19,8 +19,13 @@ workloads_dist(
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 
 \item{cut}{A numeric vector of length three to specify the breaks for the distribution,
 e.g. c(10, 15, 20)}

man/workloads_fizz.Rd

@@ -13,8 +13,13 @@ workloads_fizz(data, hrvar = "Organization", mingroup = 5, return = "plot")
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size, defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \description{
 Analyze Work Week Span distribution, and returns

man/workloads_summary.Rd

@@ -17,8 +17,13 @@ but accepts any character vector, e.g. "LevelDesignation"}
 
 \item{mingroup}{Numeric value setting the privacy threshold / minimum group size. Defaults to 5.}
 
-\item{return}{Character vector specifying what to return, defaults to "plot".
-Valid inputs are "plot" and "table".}
+\item{return}{String specifying what to return. This must be one of the following strings:
+\itemize{
+\item \code{"plot"}
+\item \code{"table"}
+}
+
+See \code{Value} for more information.}
 }
 \value{
 Returns a ggplot object by default, where 'plot' is passed in \code{return}.