Improve pluck/chuck/keep_at/discard_at documentation (#1219)

Fixes #1183

Co-authored-by: Hadley Wickham <h.wickham@gmail.com>

Author: Meghansaha

R/keep.R

@@ -63,8 +63,14 @@ compact <- function(.x, .p = identity) {
 
 #' Keep/discard elements based on their name/position
 #'
-#' @inheritParams map_at
+#' @description
+#' `keep_at()` and `discard_at()` are similar to `[` or `dplyr::select()`: they
+#' return the same type of data structure as the input, but only containing
+#' the requested elements. (If you're looking for a function similar to
+#' `[[` see [pluck()]/[chuck()]).
+#'
 #' @seealso [keep()]/[discard()] to keep/discard elements by value.
+#' @inheritParams map_at
 #' @export
 #' @examples
 #' x <- c(a = 1, b = 2, cat = 10, dog = 15, elephant = 5, e = 10)

R/pluck.R

@@ -2,8 +2,10 @@
 #'
 #' @description
 #' `pluck()` implements a generalised form of `[[` that allow you to index
-#' deeply and flexibly into data structures. It always succeeds, returning
+#' deeply and flexibly into data structures. (If you're looking for an
+#' equivalent of `[`, see [keep_at()].) `pluck()` always succeeds, returning
 #' `.default` if the index you are trying to access does not exist or is `NULL`.
+#' (If you're looking for a variant that errors, try [chuck()].)
 #'
 #' `pluck<-()` is the assignment equivalent, allowing you to modify an object
 #' deep within a nested data structure.
@@ -39,9 +41,12 @@
 #' * These accessors never partial-match. This is unlike `$` which
 #'   will select the `disp` object if you write `mtcars$di`.
 #'
-#' @seealso [attr_getter()] for creating attribute getters suitable
-#'   for use with `pluck()` and `chuck()`. [modify_in()] for
-#'   applying a function to a pluck location.
+#' @seealso
+#' * [attr_getter()] for creating attribute getters suitable for use
+#'   with `pluck()` and `chuck()`.
+#' * [modify_in()] for applying a function to a plucked location.
+#' * [keep_at()] is similar to `pluck()`, but retain the structure
+#'   of the list instead of converting it into a vector.
 #' @export
 #' @examples
 #' # Let's create a list of data structures: