Improve documentation of output type

Fixes #4699

R/arrange.R

@@ -15,13 +15,15 @@
 #' * always sorted to the end for local data, even when wrapped with `desc()`.
 #' * treated differently for remote data, depending on the backend.
 #'
+#' @return
+#' An object of the same type as `.data`. The columns will be left as is;
+#' the rows will be in different order.
 #' @export
 #' @inheritParams filter
 #' @inheritSection filter Tidy data
 #' @param ... <[`tidy-eval`][dplyr_tidy_eval]> Variables, or functions or
 #'   variables. Use [desc()] to sort a variable in descending order.
 #' @family single table verbs
-#' @return An object of the same class as `.data`.
 #' @examples
 #' arrange(mtcars, cyl, disp)
 #' arrange(mtcars, desc(disp))

R/distinct.R

@@ -11,6 +11,11 @@
 #' @param .keep_all If `TRUE`, keep all variables in `.data`.
 #'   If a combination of `...` is not distinct, this keeps the
 #'   first row of values.
+#' @return
+#' An object the same type as `.data`. If `...` is empty or `.keep_all` is
+#' `TRUE`, the columns will be unchanged. Otherwise, it will first perform a
+#' `mutate()`. The rows will be in the same order as the input, but only
+#' distinct elements will be preserved.
 #' @export
 #' @examples
 #' df <- tibble(

R/filter.R

@@ -59,7 +59,7 @@
 #'   condition evaluates to `TRUE` are kept.
 #' @param .preserve when `FALSE` (the default), the grouping structure
 #'   is recalculated based on the resulting data, otherwise it is kept as is.
-#' @return An object of the same class as `.data`.
+#' @inherit arrange return
 #' @seealso [filter_all()], [filter_if()] and [filter_at()].
 #' @export
 #' @examples

R/join.r

@@ -167,10 +167,21 @@ nest_join <- function(x, y, by = NULL, copy = FALSE, keep = FALSE, name = NULL,
 #' This page describes the details of the [join] generics when applied to
 #' data frames and tibbles.
 #'
-#' All methods treat the `x` input as primary: the return value will be the
-#' same type as `x` and the rows will in be the same order (duplicated where
-#' necessary, and where needed missing rows from `y` will be added to the end.)
-#'
+#' @return
+#' An object of the same type as `x`. The order of the rows and columns will
+#' preserved as much as possible.
+#'
+#' In mutating joins, rows may need to be duplicated, and for right/full joins,
+#' extra rows from `y` are be added to the bottom of `x`. Where the join keys
+#' are different in `x` and `y`, only keys from `x` will be included, unless
+#' `keep = TRUE`. The key columns in the output will be coerced to a common
+#' type. For example, if you're joining a integer vector with a numeric
+#' variable, the output will be a numeric vector, regardless of which is seen
+#' first.
+#'
+#' We interpret filtering joins exactly if you created the equivalent call to
+#' `filter()`: the row order, the column order, and the column types are all
+#' preserved.
 #' @inheritParams inner_join
 #' @param x,y Data frames
 #' @param ... Included for compatibility with the generic; otherwise ignored.

R/mutate.R

@@ -1,8 +1,7 @@
 #' Create or transform variables
 #'
 #' `mutate()` adds new variables and preserves existing ones;
-#' `transmute()` adds new variables and drops existing ones.  Both
-#' functions preserve the number of rows of the input.
+#' `transmute()` adds new variables and drops existing ones.
 #' New variables overwrite existing variables of the same name.
 #'
 #' @section Useful functions available in calculations of variables:
@@ -66,7 +65,10 @@
 #'   to drop a variable.  New variables overwrite existing variables
 #'   of the same name.
 #' @family single table verbs
-#' @return An object of the same class as `.data`.
+#' @return
+#' An object of the same type as `.data`. The rows will be left as; only
+#' the columns will be changed. `mutate()` preserves order of existing columns,
+#' adding new columns to the right. `transmute()` drops existing columns.
 #' @examples
 #' # Newly created variables are available immediately
 #' mtcars %>% as_tibble() %>% mutate(

R/pull.R

@@ -7,6 +7,7 @@
 #' @inheritParams tidyselect::vars_pull
 #' @param name An optional parameter that specifies the column to be used
 #'   as names for a named vector. Specified in a similar manner as \code{var}.
+#' @return A vector the same size as `.data`.
 #' @export
 #' @examples
 #' mtcars %>% pull(-1)

R/select.R

@@ -54,7 +54,9 @@
 #'
 #'   Use named arguments, e.g. `new_name = old_name`, to rename selected
 #'   variables.
-#' @return An object of the same class as `.data`.
+#' @return
+#' An object of the same type as `.data`. The rows will be left as; only
+#' the columns (position and/or name) will be changed.
 #' @family single table verbs
 #' @export
 #' @examples

R/slice.R

@@ -14,6 +14,7 @@
 #'   The values provided must be either all positive or all negative.
 #'   Indices beyond the number of rows in the input are silently ignored.
 #' @inheritParams filter
+#' @inherit arrange return
 #' @inheritSection filter Tidy data
 #' @export
 #' @examples

R/summarise.R

@@ -39,11 +39,14 @@
 #'   The value should be an expression that returns a single value like
 #'   `min(x)`, `n()`, or `sum(is.na(y))`.
 #' @family single table verbs
-#' @return An object of the same class as `.data`.
+#' @return
+#' An object of the same class as `.data`. It will contain one column for
+#' each grouping variable and each expression you supply. It will have
+#' one row for each combination of the grouping variables.
 #'
-#'   If `.data` is grouped, then the last group will be dropped,
-#'   e.g.`df %>% group_by(x, y) %>% summarise(n())` will be grouped by
-#'   `x`. This happens because each group now occupies only a single row.
+#' If `.data` is grouped, then the last group will be dropped,
+#' e.g.`df %>% group_by(x, y) %>% summarise(n())` will be grouped by
+#' `x`. This happens because each group now occupies only a single row.
 #' @examples
 #' # A summary applied to ungrouped tbl returns a single row
 #' mtcars %>%