better documentation for local parameter of writing functions

R/doc.R

@@ -7,3 +7,22 @@
 #'
 #' @keywords internal
 doc_file <- function(file) {}
+
+
+
+#' @title Package-wide description of `local` parameter
+#' @description A dummy function to be referred by `@inheritParams` for a
+#'   parameter documentation.
+#' 
+#' @param local Logical, defaulting to `FALSE`. If `TRUE`, the function will
+#'   also create a local copy of the file at the specified path. Note that some
+#'   writing functions might not overwrite existing files unless explicitly
+#'   allowed. Typically, such functions have a parameter (often named
+#'   `overwrite`) to control this behavior. Check the documentation of the
+#'   writing function used to determine the exact parameter name and pass it
+#'   through the `...` argument if necessary. Alternatively, you can define an
+#'   anonymous function for `fun` that calls a writing function with the
+#'   overwriting option enabled.
+#'   
+#' @keywords internal
+doc_local <- function(local) {}

R/drive_transfer.R

@@ -97,13 +97,12 @@ cloud_drive_download <- function(file, root = NULL) {
 #'   
 #' @inheritParams doc_file
 #' @inheritParams cloud_drive_ls
+#' @inheritParams doc_local
 #' 
 #' @param x An R object to be written to Google Drive.
 #' @param fun A custom writing function. If `NULL` (default), the appropriate
 #'   writing function will be inferred based on the file's extension.
 #' @param ... Additional arguments to pass to the writing function `fun`.
-#' @param local Logical. If `TRUE`, a local copy of the file will also be
-#'   created at the specified path. Default is `FALSE`.
 #' 
 #' @inheritSection cloud_guess_write_fun Default writing functions
 #' 

R/s3_transfer.R

@@ -92,13 +92,12 @@ cloud_s3_download <- function(file, root = NULL) {
 #'   
 #' @inheritParams doc_file
 #' @inheritParams cloud_s3_ls
+#' @inheritParams doc_local
 #' 
 #' @param x An R object to be written to S3.
 #' @param fun A custom writing function. If `NULL` (default), the appropriate
 #'   writing function will be inferred based on the file's extension.
 #' @param ... Additional arguments to pass to the writing function `fun`.
-#' @param local Logical. If `TRUE`, a local copy of the file will also be
-#'   created at the specified path. Default is `FALSE`.
 #' 
 #' @inheritSection cloud_guess_write_fun Default writing functions
 #'