docs: consistent return docs

R/workpatterns_hclust.R

@@ -19,13 +19,17 @@
 #'
 #' @param data A data frame containing data from the Hourly Collaboration query.
 #' @param k Numeric vector to specify the `k` number of clusters to cut by.
-#' @param return Character vector to specify what to return. Valid options include:
-#'   - `"plot"`: returns a bar plot (default)
-#'   - `"data"`: returns raw data with the clusters
-#'   - `"table"`: returns a summary table
-#'   - `"plot-area"`: returns an overlapping area plot
-#'   - `"hclust"`: returns the hierarchical model generated by the function
-#'   - `"dist"`: returns the distance matrix used to build the clustering model
+#'
+#' @param return String specifying what to return. This must be one of the
+#'   following strings:
+#'   - `"plot"`
+#'   - `"data"`
+#'   - `"table"`
+#'   - `"plot-area"`
+#'   - `"hclust"`
+#'   - `"dist"`
+#'
+#' See `Value` for more information.
 #'
 #' @param values Character vector to specify whether to return percentages
 #' or absolute values in "data" and "plot". Valid values are:
@@ -44,8 +48,15 @@
 #' e.g. "1700"
 #'
 #' @return
-#' The summary table returned by `return == "table"` represent percentiles of signals,
-#' e.g. x% of signals are sent by y hour of the day.
+#' A different output is returned depending on the value passed to the `return`
+#' argument:
+#'   - `"plot"`: ggplot object of a bar plot (default)
+#'   - `"data"`: data frame containing raw data with the clusters
+#'   - `"table"`: data frame containing a summary table. Percentages of signals
+#'   are shown, e.g. x% of signals are sent by y hour of the day.
+#'   - `"plot-area"`: ggplot object. An overlapping area plot
+#'   - `"hclust"`: `hclust` object for the hierarchical model
+#'   - `"dist"`: distance matrix used to build the clustering model
 #'
 #' @import dplyr
 #' @import tidyselect

man/workpatterns_hclust.Rd

@@ -19,15 +19,18 @@ workpatterns_hclust(
 
 \item{k}{Numeric vector to specify the \code{k} number of clusters to cut by.}
 
-\item{return}{Character vector to specify what to return. Valid options include:
+\item{return}{String specifying what to return. This must be one of the
+following strings:
 \itemize{
-\item \code{"plot"}: returns a bar plot (default)
-\item \code{"data"}: returns raw data with the clusters
-\item \code{"table"}: returns a summary table
-\item \code{"plot-area"}: returns an overlapping area plot
-\item \code{"hclust"}: returns the hierarchical model generated by the function
-\item \code{"dist"}: returns the distance matrix used to build the clustering model
-}}
+\item \code{"plot"}
+\item \code{"data"}
+\item \code{"table"}
+\item \code{"plot-area"}
+\item \code{"hclust"}
+\item \code{"dist"}
+}
+
+See \code{Value} for more information.}
 
 \item{values}{Character vector to specify whether to return percentages
 or absolute values in "data" and "plot". Valid values are:
@@ -52,8 +55,17 @@ e.g. "0900"}
 e.g. "1700"}
 }
 \value{
-The summary table returned by \code{return == "table"} represent percentiles of signals,
-e.g. x\% of signals are sent by y hour of the day.
+A different output is returned depending on the value passed to the \code{return}
+argument:
+\itemize{
+\item \code{"plot"}: ggplot object of a bar plot (default)
+\item \code{"data"}: data frame containing raw data with the clusters
+\item \code{"table"}: data frame containing a summary table. Percentages of signals
+are shown, e.g. x\% of signals are sent by y hour of the day.
+\item \code{"plot-area"}: ggplot object. An overlapping area plot
+\item \code{"hclust"}: \code{hclust} object for the hierarchical model
+\item \code{"dist"}: distance matrix used to build the clustering model
+}
 }
 \description{
 \ifelse{html}{\out{<a href='https://www.tidyverse.org/lifecycle/#experimental'><img src='figures/lifecycle-experimental.svg' alt='Experimental lifecycle'></a>}}{\strong{Experimental}}