From 4f1d7a616c50f70a48f01a44e6dafc135bb4a4c9 Mon Sep 17 00:00:00 2001
From: Aris Paschalidis <aris.paschalidis@gmail.com>
Date: Mon, 8 Aug 2022 11:26:43 +0300
Subject: [PATCH] Add return value to all docs

---
 R/chromosome-map.R              |  3 +++
 R/convert.R                     |  4 +++-
 R/example.R                     |  2 ++
 R/filter.R                      | 13 +++++++++++--
 R/mutation-frequency.R          |  2 ++
 R/mutation-prevalence.R         |  2 ++
 R/plot_coverage.R               |  2 ++
 R/read-tbl.R                    | 10 ++++------
 R/themes.R                      |  2 ++
 man/chromosome-map.Rd           |  4 ++++
 man/convert_single.Rd           |  5 ++++-
 man/custom_themes.Rd            |  3 +++
 man/filter.Rd                   | 14 ++++++++++++--
 man/miplicorn-package.Rd        |  2 +-
 man/miplicorn_example.Rd        |  3 +++
 man/plot_coverage.Rd            |  3 +++
 man/plot_mutation_frequency.Rd  |  3 +++
 man/plot_mutation_prevalence.Rd |  3 +++
 man/read-tbl.Rd                 | 10 ++++------
 19 files changed, 71 insertions(+), 19 deletions(-)

diff --git a/R/chromosome-map.R b/R/chromosome-map.R
index b77c13a..53e98d4 100644
--- a/R/chromosome-map.R
+++ b/R/chromosome-map.R
@@ -25,6 +25,9 @@
 #' @param ... <[`dynamic-dots`][rlang::dyn-dots]> Additional arguments passed to
 #'   internal plotting functions.
 #'
+#' @return A [chromoMap][chromoMap::chromoMap] or
+#'   [karyoploteR](https://bernatgel.github.io/karyoploter_tutorial/) object.
+#'
 #' @seealso See the [chromoMap][chromoMap::chromoMap] and
 #'   [karyoploteR](https://bernatgel.github.io/karyoploter_tutorial/) packages
 #'   to create custom chromosome maps.
diff --git a/R/convert.R b/R/convert.R
index c0bb6ad..b8f6e4b 100644
--- a/R/convert.R
+++ b/R/convert.R
@@ -7,7 +7,9 @@
 #' Conversion is case-insensitive, but always returns capitalized 1-letter and
 #' 3-letter abbreviations in title-case.
 #'
-#' @param str String containing amino acids to convert.
+#' @param str Character vector containing amino acids to convert.
+#'
+#' @return Character vector with converted amino acid abbreviations.
 #'
 #' @aliases convert
 #' @export
diff --git a/R/example.R b/R/example.R
index 0d38836..8e8f95d 100644
--- a/R/example.R
+++ b/R/example.R
@@ -6,6 +6,8 @@
 #'
 #' @param path Name of file. If `NULL`, all example files will be listed.
 #'
+#' @return A local filepath or a list of all available files.
+#'
 #' @aliases example
 #' @export
 #' @examples
diff --git a/R/filter.R b/R/filter.R
index 63c12a4..e5bb582 100644
--- a/R/filter.R
+++ b/R/filter.R
@@ -62,10 +62,19 @@ filter_fn_factory <- function(.col, .type = c("numeric", "character")) {
 #'
 #' @param .data A data frame, data frame extension (e.g. a tibble), or a lazy
 #'   data frame (e.g. from dbplyr or dtplyr).
-#' @param .value Filtering value. Data greater than or equal to the value will
-#'   be kept.
+#' @param .value Filtering value. If a number, data greater than or equal to the
+#'   value will be kept. If a string, data equal to the value will be kept.
 #' @inheritParams dplyr::filter
 #'
+#' @return
+#' An object of the same type as `.data`. The output has the following
+#' properties:
+#'
+#' * Rows are a subset of the input, but appear in the same order.
+#' * Columns are not modified.
+#' * The number of groups may be reduced (if `.preserve` is not `TRUE`).
+#' * Data frame attributes are preserved.
+#'
 #' @name filter
 #' @seealso [dplyr::filter()] for more complex filtering operations.
 #' @examples
diff --git a/R/mutation-frequency.R b/R/mutation-frequency.R
index 8d51135..106ffe7 100644
--- a/R/mutation-frequency.R
+++ b/R/mutation-frequency.R
@@ -109,6 +109,8 @@ mutation_frequency.ref_alt_cov_tbl <- function(data, threshold) {
 #'   of [mutation_frequency()].
 #' @param ...	Other arguments passed to specific methods.
 #'
+#' @return A [ggplot2][ggplot2::ggplot2-package] object.
+#'
 #' @export
 #' @seealso [mutation_frequency()] for generating the data for plotting.
 #' @examples
diff --git a/R/mutation-prevalence.R b/R/mutation-prevalence.R
index f92bbdd..4189048 100644
--- a/R/mutation-prevalence.R
+++ b/R/mutation-prevalence.R
@@ -143,6 +143,8 @@ mutation_prevalence.geno_tbl <- function(data, ...) {
 #'   of [mutation_prevalence()].
 #' @param ...	Other arguments passed to specific methods.
 #'
+#' @return A [ggplot2][ggplot2::ggplot2-package] object.
+#'
 #' @export
 #' @seealso [mutation_prevalence()] for generating the data for plotting.
 #' @examples
diff --git a/R/plot_coverage.R b/R/plot_coverage.R
index 3139bb3..47fe9f4 100644
--- a/R/plot_coverage.R
+++ b/R/plot_coverage.R
@@ -10,6 +10,8 @@
 #' @param group_by The grouping variable. The average coverage is computed for
 #'   each unique value of the variable.
 #'
+#' @return A [ggplot2][ggplot2::ggplot2-package] object.
+#'
 #' @export
 #' @examples
 #' # Read example data
diff --git a/R/read-tbl.R b/R/read-tbl.R
index 09f2fee..02b7277 100644
--- a/R/read-tbl.R
+++ b/R/read-tbl.R
@@ -17,7 +17,7 @@
 #' sequenced.
 #'
 #' @section Useful filter functions:
-#' The [dplyr::filter()] function is employed to subset the rows of the data
+#' The [dplyr::filter()] function is employed to subset the rows of the data by
 #' applying the expressions in `...` to the column values to determine which
 #' rows should be retained.
 #'
@@ -47,11 +47,9 @@
 #' @param gene `r lifecycle::badge("deprecated")` The gene(s) to filter to.
 #'
 #' @return
-#' A [`tibble()`][tibble::tibble-package]. The first six columns contain the
-#' metadata associated with each sample and mutation. The last column contains
-#' the information parsed from the table. In some cases, this may be the
-#' umi_count and in other cases it may be the coverage of the associated data
-#' point.
+#' A [`tibble()`][tibble::tibble-package] subclass. Each function defines a
+#' unique subclass to store the data. Data typically contains the sample,
+#' associated metadata, and the value of interest.
 #'
 #' @seealso [vroom::vroom()] [dplyr::filter()]
 #' @name read-tbl
diff --git a/R/themes.R b/R/themes.R
index 44ffd75..644e1a0 100644
--- a/R/themes.R
+++ b/R/themes.R
@@ -9,6 +9,8 @@
 #' @param base_line_size Base size for line elements.
 #' @param base_rect_size Base size for rect elements.
 #'
+#' @return A [ggplot2][ggplot2::theme] theme.
+#'
 #' @importFrom ggplot2 %+replace%
 #' @examples
 #' library("ggplot2")
diff --git a/man/chromosome-map.Rd b/man/chromosome-map.Rd
index 4034d9a..3da9a5d 100644
--- a/man/chromosome-map.Rd
+++ b/man/chromosome-map.Rd
@@ -36,6 +36,10 @@ probe set.}
 \item{...}{<\code{\link[rlang:dyn-dots]{dynamic-dots}}> Additional arguments passed to
 internal plotting functions.}
 }
+\value{
+A \link[chromoMap:chromoMap]{chromoMap} or
+\href{https://bernatgel.github.io/karyoploter_tutorial/}{karyoploteR} object.
+}
 \description{
 Render a graphics visualization of entire chromosomes or chromosomal regions.
 Annotate multiple targeted regions to visualize probe targets.
diff --git a/man/convert_single.Rd b/man/convert_single.Rd
index c2abb38..f9e1536 100644
--- a/man/convert_single.Rd
+++ b/man/convert_single.Rd
@@ -11,7 +11,10 @@ convert_single(str)
 convert_three(str)
 }
 \arguments{
-\item{str}{String containing amino acids to convert.}
+\item{str}{Character vector containing amino acids to convert.}
+}
+\value{
+Character vector with converted amino acid abbreviations.
 }
 \description{
 \code{convert_single()} converts the 1-letter amino acid abbreviation to the
diff --git a/man/custom_themes.Rd b/man/custom_themes.Rd
index c837e3b..383dd17 100644
--- a/man/custom_themes.Rd
+++ b/man/custom_themes.Rd
@@ -28,6 +28,9 @@ theme_rainbow(
 
 \item{base_rect_size}{Base size for rect elements.}
 }
+\value{
+A \link[ggplot2:theme]{ggplot2} theme.
+}
 \description{
 These are custom \code{ggplot2} themes which control all non-data display. You
 may further tweak components of these themes using \code{\link[ggplot2:theme]{ggplot2::theme()}}.
diff --git a/man/filter.Rd b/man/filter.Rd
index 45a995c..dc14fd3 100644
--- a/man/filter.Rd
+++ b/man/filter.Rd
@@ -29,13 +29,23 @@ filter_targeted(.data, .value, .preserve = FALSE)
 \item{.data}{A data frame, data frame extension (e.g. a tibble), or a lazy
 data frame (e.g. from dbplyr or dtplyr).}
 
-\item{.value}{Filtering value. Data greater than or equal to the value will
-be kept.}
+\item{.value}{Filtering value. If a number, data greater than or equal to the
+value will be kept. If a string, data equal to the value will be kept.}
 
 \item{.preserve}{Relevant when the \code{.data} input is grouped.
 If \code{.preserve = FALSE} (the default), the grouping structure
 is recalculated based on the resulting data, otherwise the grouping is kept as is.}
 }
+\value{
+An object of the same type as \code{.data}. The output has the following
+properties:
+\itemize{
+\item Rows are a subset of the input, but appear in the same order.
+\item Columns are not modified.
+\item The number of groups may be reduced (if \code{.preserve} is not \code{TRUE}).
+\item Data frame attributes are preserved.
+}
+}
 \description{
 These \verb{filter_*()} functions are used to subset a data frame. Each function
 subsets rows based on the value of one column. For numeric columns, a row
diff --git a/man/miplicorn-package.Rd b/man/miplicorn-package.Rd
index 098dd0a..3a3be1f 100644
--- a/man/miplicorn-package.Rd
+++ b/man/miplicorn-package.Rd
@@ -4,7 +4,7 @@
 \name{miplicorn-package}
 \alias{miplicorn}
 \alias{miplicorn-package}
-\title{miplicorn: A Framework for MIP and Amplicon Analysis}
+\title{miplicorn: A Framework for Molecular Inversion Probe and Amplicon Analysis}
 \description{
 \if{html}{\figure{logo.png}{options: style='float: right' alt='logo' width='120'}}
 
diff --git a/man/miplicorn_example.Rd b/man/miplicorn_example.Rd
index c09eb28..435767e 100644
--- a/man/miplicorn_example.Rd
+++ b/man/miplicorn_example.Rd
@@ -10,6 +10,9 @@ miplicorn_example(path = NULL)
 \arguments{
 \item{path}{Name of file. If \code{NULL}, all example files will be listed.}
 }
+\value{
+A local filepath or a list of all available files.
+}
 \description{
 miplicorn contains several example files in its 'inst/extdata' directory.
 This function can be used to access file paths.
diff --git a/man/plot_coverage.Rd b/man/plot_coverage.Rd
index 76ff83a..d7322b7 100644
--- a/man/plot_coverage.Rd
+++ b/man/plot_coverage.Rd
@@ -19,6 +19,9 @@ data frame (e.g. from dbplyr or dtplyr).}
 \item{group_by}{The grouping variable. The average coverage is computed for
 each unique value of the variable.}
 }
+\value{
+A \link[ggplot2:ggplot2-package]{ggplot2} object.
+}
 \description{
 Create a bar chart visualizing the average coverage across a given grouping
 variable. The color of each bar represents the magnitude of the mean
diff --git a/man/plot_mutation_frequency.Rd b/man/plot_mutation_frequency.Rd
index aea5821..7c893be 100644
--- a/man/plot_mutation_frequency.Rd
+++ b/man/plot_mutation_frequency.Rd
@@ -18,6 +18,9 @@ of \code{\link[=mutation_frequency]{mutation_frequency()}}.}
 
 \item{...}{Other arguments passed to specific methods.}
 }
+\value{
+A \link[ggplot2:ggplot2-package]{ggplot2} object.
+}
 \description{
 Plot the frequency of mutations generated by \code{\link[=mutation_frequency]{mutation_frequency()}}.
 The frequency is plotted on the y-axis and the amino acid change is plotted
diff --git a/man/plot_mutation_prevalence.Rd b/man/plot_mutation_prevalence.Rd
index 183bd08..1e294ca 100644
--- a/man/plot_mutation_prevalence.Rd
+++ b/man/plot_mutation_prevalence.Rd
@@ -18,6 +18,9 @@ of \code{\link[=mutation_prevalence]{mutation_prevalence()}}.}
 
 \item{...}{Other arguments passed to specific methods.}
 }
+\value{
+A \link[ggplot2:ggplot2-package]{ggplot2} object.
+}
 \description{
 Plot the prevalence of mutations generated by \code{\link[=mutation_prevalence]{mutation_prevalence()}}.
 The prevalence is plotted on the y-axis and the amino acid change is plotted
diff --git a/man/read-tbl.Rd b/man/read-tbl.Rd
index 50ede68..a6d6128 100644
--- a/man/read-tbl.Rd
+++ b/man/read-tbl.Rd
@@ -56,11 +56,9 @@ to.}
 \item{gene}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} The gene(s) to filter to.}
 }
 \value{
-A \code{\link[tibble:tibble-package]{tibble()}}. The first six columns contain the
-metadata associated with each sample and mutation. The last column contains
-the information parsed from the table. In some cases, this may be the
-umi_count and in other cases it may be the coverage of the associated data
-point.
+A \code{\link[tibble:tibble-package]{tibble()}} subclass. Each function defines a
+unique subclass to store the data. Data typically contains the sample,
+associated metadata, and the value of interest.
 }
 \description{
 The \verb{read_tbl_*()} family of functions is designed to read data tables
@@ -81,7 +79,7 @@ sequenced.
 
 \section{Useful filter functions}{
 
-The \code{\link[dplyr:filter]{dplyr::filter()}} function is employed to subset the rows of the data
+The \code{\link[dplyr:filter]{dplyr::filter()}} function is employed to subset the rows of the data by
 applying the expressions in \code{...} to the column values to determine which
 rows should be retained.