From b212852412b5fda501bcf5c68d3d7dbbeb317208 Mon Sep 17 00:00:00 2001
From: Finn Roberts <finn.a.roberts@gmail.com>
Date: Thu, 30 Oct 2025 14:55:43 +0100
Subject: [PATCH 1/2] Clarify `set_ipums_api_key()` usage (resolves #95)

---
 R/api_helpers.R          | 12 ++++++++++--
 man/set_ipums_api_key.Rd | 11 ++++++++++-
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/R/api_helpers.R b/R/api_helpers.R
index 3113ea24..24675cfc 100644
--- a/R/api_helpers.R
+++ b/R/api_helpers.R
@@ -75,9 +75,17 @@ ipums_data_collections <- function() {
 #' @seealso
 #' [set_ipums_default_collection()] to set a default collection.
 #'
+#' @examples
+#' # Set for single session
+#' set_ipums_api_key("your-api-key-here")
+#'
+#' \dontrun{
+#' # Save key to .Renviron for future sessions
+#' set_ipums_api_key("your-api-key-here", save = TRUE)
+#' }
 #' @export
 set_ipums_api_key <- function(api_key,
-                              save = overwrite,
+                              save = NULL,
                               overwrite = FALSE,
                               unset = FALSE) {
   if (unset) {
@@ -85,7 +93,7 @@ set_ipums_api_key <- function(api_key,
   } else {
     api_key <- set_ipums_envvar(
       IPUMS_API_KEY = api_key,
-      save = save,
+      save = save %||% overwrite,
       overwrite = overwrite
     )
   }
diff --git a/man/set_ipums_api_key.Rd b/man/set_ipums_api_key.Rd
index 01edc21a..67a564fb 100644
--- a/man/set_ipums_api_key.Rd
+++ b/man/set_ipums_api_key.Rd
@@ -4,7 +4,7 @@
 \alias{set_ipums_api_key}
 \title{Set your IPUMS API key}
 \usage{
-set_ipums_api_key(api_key, save = overwrite, overwrite = FALSE, unset = FALSE)
+set_ipums_api_key(api_key, save = NULL, overwrite = FALSE, unset = FALSE)
 }
 \arguments{
 \item{api_key}{API key associated with your user account.}
@@ -37,6 +37,15 @@ from \href{https://walker-data.com/tidycensus/}{tidycensus}.
 
 Learn more about the IPUMS API in \code{vignette("ipums-api")}.
 }
+\examples{
+# Set for single session
+set_ipums_api_key("your-api-key-here")
+
+\dontrun{
+# Save key to .Renviron for future sessions
+set_ipums_api_key("your-api-key-here", save = TRUE)
+}
+}
 \seealso{
 \code{\link[=set_ipums_default_collection]{set_ipums_default_collection()}} to set a default collection.
 }

From aafffbc227f55e4f9db842273a7473bf32553b19 Mon Sep 17 00:00:00 2001
From: Derek Burk <burkx031@umn.edu>
Date: Mon, 24 Nov 2025 11:40:56 -0600
Subject: [PATCH 2/2] Revert the default value of save argument to `overwrite`
 in set_ipums_api_key, and add two more examples; potentially resolves #95

---
 R/api_helpers.R          | 10 ++++++++--
 man/set_ipums_api_key.Rd |  8 +++++++-
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/R/api_helpers.R b/R/api_helpers.R
index 24675cfc..3c2fcf7b 100644
--- a/R/api_helpers.R
+++ b/R/api_helpers.R
@@ -82,10 +82,16 @@ ipums_data_collections <- function() {
 #' \dontrun{
 #' # Save key to .Renviron for future sessions
 #' set_ipums_api_key("your-api-key-here", save = TRUE)
+#'
+#' # Overwrite existing key in .Renviron
+#' set_ipums_api_key("your-api-key-here", overwrite = TRUE)
+#'
+#' # Remove existing key from .Renviron
+#' set_ipums_api_key("your-api-key-here", unset = TRUE)
 #' }
 #' @export
 set_ipums_api_key <- function(api_key,
-                              save = NULL,
+                              save = overwrite,
                               overwrite = FALSE,
                               unset = FALSE) {
   if (unset) {
@@ -93,7 +99,7 @@ set_ipums_api_key <- function(api_key,
   } else {
     api_key <- set_ipums_envvar(
       IPUMS_API_KEY = api_key,
-      save = save %||% overwrite,
+      save = save,
       overwrite = overwrite
     )
   }
diff --git a/man/set_ipums_api_key.Rd b/man/set_ipums_api_key.Rd
index 67a564fb..5c8f3609 100644
--- a/man/set_ipums_api_key.Rd
+++ b/man/set_ipums_api_key.Rd
@@ -4,7 +4,7 @@
 \alias{set_ipums_api_key}
 \title{Set your IPUMS API key}
 \usage{
-set_ipums_api_key(api_key, save = NULL, overwrite = FALSE, unset = FALSE)
+set_ipums_api_key(api_key, save = overwrite, overwrite = FALSE, unset = FALSE)
 }
 \arguments{
 \item{api_key}{API key associated with your user account.}
@@ -44,6 +44,12 @@ set_ipums_api_key("your-api-key-here")
 \dontrun{
 # Save key to .Renviron for future sessions
 set_ipums_api_key("your-api-key-here", save = TRUE)
+
+# Overwrite existing key in .Renviron
+set_ipums_api_key("your-api-key-here", overwrite = TRUE)
+
+# Remove existing key from .Renviron
+set_ipums_api_key("your-api-key-here", unset = TRUE)
 }
 }
 \seealso{