Superseded with_groups()

Fixes #6582

DESCRIPTION

@@ -64,4 +64,4 @@ Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true
 Roxygen: list(markdown = TRUE)
-RoxygenNote: 7.2.2
+RoxygenNote: 7.2.3

NEWS.md

@@ -1,5 +1,7 @@
 # dplyr (development version)
 
+* `with_groups()` is superseded in favour of `.by` (#6582)
+
 * `slice()` with no inputs now returns 0 rows. This is mostly for theoretical
   consistency (#6573).
 

R/groups-with.R

@@ -1,10 +1,11 @@
 #' Perform an operation with temporary groups
 #'
 #' @description
-#' `r lifecycle::badge("experimental")`
+#' `r lifecycle::badge("superseded")`
 #'
-#' This is an experimental new function that allows you to modify the grouping
-#' variables for a single operation.
+#' This was an experimental function that allows you to modify the grouping
+#' variables for a single operation; it is superseded in favour of using the
+#' `.by` argument to individual verbs.
 #'
 #' @param .data A data frame
 #' @param .groups <[`tidy-select`][dplyr_tidy_select]> One or more variables
@@ -16,22 +17,16 @@
 #' @param .f Function to apply to regrouped data.
 #'   Supports purrr-style `~` syntax
 #' @param ... Additional arguments passed on to `...`.
+#' @keywords internal
 #' @export
 #' @examples
 #' df <- tibble(g = c(1, 1, 2, 2, 3), x = runif(5))
-#' df %>%
-#'   with_groups(g, mutate, x_mean = mean(x))
-#' df %>%
-#'   with_groups(g, ~ mutate(.x, x1 = first(x)))
 #'
+#' # Old
 #' df %>%
-#'   group_by(g) %>%
-#'   with_groups(NULL, mutate, x_mean = mean(x))
-#'
-#' # NB: grouping can't be restored if you remove the grouping variables
-#' df %>%
-#'   group_by(g) %>%
-#'   with_groups(NULL, mutate, g = NULL)
+#'   with_groups(g, mutate, x_mean = mean(x))
+#' # New
+#' df %>% mutate(x_mean = mean(x), .by = g)
 with_groups <- function(.data, .groups, .f, ...) {
   lifecycle::signal_stage("experimental", "with_groups()")
   loc <- tidyselect::eval_select(enquo(.groups), data = tbl_ptype(.data))

_pkgdown.yml

@@ -109,7 +109,6 @@ reference:
   - group_modify
   - group_trim
   - group_split
-  - with_groups
 
 - title: Superseded
   desc: >
@@ -123,6 +122,7 @@ reference:
   - ends_with("_at")
   - all_vars
   - vars
+  - with_groups
 
 - title: Remote tables
   contents: