From 962d50a811f245d09227427d3e70f6c1cc86eb08 Mon Sep 17 00:00:00 2001
From: Hadley Wickham <h.wickham@gmail.com>
Date: Fri, 20 Dec 2024 14:23:52 -0600
Subject: [PATCH] Clarify `.multi` option

#593
---
 R/req-body.R    |  3 ++-
 R/req-url.R     |  7 ++++---
 man/req_body.Rd | 10 ++++++----
 man/req_url.Rd  |  7 ++++---
 4 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/R/req-body.R b/R/req-body.R
index f9786731..1087e4d4 100644
--- a/R/req-body.R
+++ b/R/req-body.R
@@ -137,7 +137,8 @@ req_body_json_modify <- function(req, ...) {
 #'   data in the body.
 #'
 #'   * For `req_body_form()`, the values must be strings (or things easily
-#'     coerced to strings);
+#'     coerced to strings). Vectors are convertd to strings using the
+#'     value of `.multi`.
 #'   * For `req_body_multipart()` the values must be strings or objects
 #'     produced by [curl::form_file()]/[curl::form_data()].
 #'   * For `req_body_json_modify()`, any simple data made from atomic vectors
diff --git a/R/req-url.R b/R/req-url.R
index d168e429..a35b1489 100644
--- a/R/req-url.R
+++ b/R/req-url.R
@@ -55,10 +55,11 @@ req_url <- function(req, url) {
 #'   * `"error"`, the default, throws an error.
 #'   * `"comma"`, separates values with a `,`, e.g. `?x=1,2`.
 #'   * `"pipe"`, separates values with a `|`, e.g. `?x=1|2`.
-#'   * `"explode"`, turns each element into its own parameter, e.g. `?x=1&x=2`.
+#'   * `"explode"`, turns each element into its own parameter, e.g. `?x=1&x=2`
 #'
-#'   If none of these functions work, you can alternatively supply a function
-#'   that takes a character vector and returns a string.
+#'   If none of these options work for your needs, you can instead supply a
+#'   function that takes a character vector of argument values and returns a
+#'   a single string.
 req_url_query <- function(.req,
                           ...,
                           .multi = c("error", "comma", "pipe", "explode")) {
diff --git a/man/req_body.Rd b/man/req_body.Rd
index cf416284..6517608a 100644
--- a/man/req_body.Rd
+++ b/man/req_body.Rd
@@ -53,7 +53,8 @@ or an empty list (\code{"list"}).}
 data in the body.
 \itemize{
 \item For \code{req_body_form()}, the values must be strings (or things easily
-coerced to strings);
+coerced to strings). Vectors are convertd to strings using the
+value of \code{.multi}.
 \item For \code{req_body_multipart()} the values must be strings or objects
 produced by \code{\link[curl:multipart]{curl::form_file()}}/\code{\link[curl:multipart]{curl::form_data()}}.
 \item For \code{req_body_json_modify()}, any simple data made from atomic vectors
@@ -69,11 +70,12 @@ containing multiple values:
 \item \code{"error"}, the default, throws an error.
 \item \code{"comma"}, separates values with a \verb{,}, e.g. \verb{?x=1,2}.
 \item \code{"pipe"}, separates values with a \code{|}, e.g. \code{?x=1|2}.
-\item \code{"explode"}, turns each element into its own parameter, e.g. \code{?x=1&x=2}.
+\item \code{"explode"}, turns each element into its own parameter, e.g. \code{?x=1&x=2}
 }
 
-If none of these functions work, you can alternatively supply a function
-that takes a character vector and returns a string.}
+If none of these options work for your needs, you can instead supply a
+function that takes a character vector of argument values and returns a
+a single string.}
 }
 \value{
 A modified HTTP \link{request}.
diff --git a/man/req_url.Rd b/man/req_url.Rd
index 87bdc284..ca5b50b6 100644
--- a/man/req_url.Rd
+++ b/man/req_url.Rd
@@ -34,11 +34,12 @@ containing multiple values:
 \item \code{"error"}, the default, throws an error.
 \item \code{"comma"}, separates values with a \verb{,}, e.g. \verb{?x=1,2}.
 \item \code{"pipe"}, separates values with a \code{|}, e.g. \code{?x=1|2}.
-\item \code{"explode"}, turns each element into its own parameter, e.g. \code{?x=1&x=2}.
+\item \code{"explode"}, turns each element into its own parameter, e.g. \code{?x=1&x=2}
 }
 
-If none of these functions work, you can alternatively supply a function
-that takes a character vector and returns a string.}
+If none of these options work for your needs, you can instead supply a
+function that takes a character vector of argument values and returns a
+a single string.}
 }
 \value{
 A modified HTTP \link{request}.